[Hibernate-issues] [Hibernate-JIRA] Commented: (HB-239) javadoc build spits >200 warnings

[<leg...@at...>]

The following comment has been added to this issue:

     Author: Christian Bauer
    Created: Fri, 8 Aug 2003 7:07 PM
       Body:
We have two levels of errors here:

- Warnings reported by the "first sentence" detector of the JavaDoc generator. 

- Errors in the JavaDoc (wrong parameter names, missing tags) detected by IntelliJ inspector, no warnings in generator.

I fixed all of the generator warnings by tricking the "first sentence" detection. I've to commit about 30 files from the src/ directory. This stuff is really crazy:

/**
 * A first sentence.
 * @param foo
 */

This is broken. Whenever you use a first sentence (detected by: first period with trailing space, new line or first tag), you have to add a second sentence if a tag is following.

/**
 * A first sentence. This is for JavaDoc.
 * @param foo
 */

This works. Don't use questionmarks to end the first sentence. If you only have a single sentence, don't include parameters, exceptions and return tags. Don't end first sentences in the next line:


/**
 * This is a broken
 * first sentence. It will produce a warning.
 * @param foo
 */

Oh well. IntelliJ (use it!) detects all of the JavaDoc errors  but doesn't check the "first sentence" algorithm. I've also found some strange behaviour if you include a questionmark _anywhere_ in the first sentence. Don't do it.

I'll commit the changes on request. We still have a couple of hundred non-warning (but real) errors to fix. Everyone use a good IDE and fix this while working with the source. I won't spent three days for this :)

---------------------------------------------------------------------
View the issue:

  http://opensource.atlassian.com/projects/hibernate/secure/ViewIssue.jspa?key=HB-239


Here is an overview of the issue:
---------------------------------------------------------------------
        Key: HB-239
    Summary: javadoc build spits >200 warnings
       Type: Bug

     Status: Assigned
   Priority: Trivial

    Project: Hibernate2
 Components: 
             core
   Versions:
             2.0.2

   Assignee: Christian Bauer
   Reporter: Gavin King

    Created: Thu, 7 Aug 2003 7:43 AM
    Updated: Thu, 7 Aug 2003 7:43 AM
Environment: Ant build

Description:
The javadoc build currently spits many warnings, all the same.


---------------------------------------------------------------------
JIRA INFORMATION:
This message is automatically generated by JIRA.

If you think it was sent incorrectly contact one of the administrators:
   http://opensource.atlassian.com/projects/hibernate/secure/Administrators.jspa

If you want more information on JIRA, or have a bug to report see:
   http://www.atlassian.com/software/jira