Re: Javadoc warning with api20 interface FetchPlan

[Craig L Russell <Cr...@Sun.COM>]

Hi Michael,

Please go ahead and check in the fix.

Craig

On Mar 16, 2006, at 12:12 PM, Michael Bouschen wrote:

> Hi,
>
> when building the api20 project using JDK1.4 I get a javadoc  
> warning from the FetchPlan interface. You find the warning in the  
> attached text file. I propose to change the javadoc comment to  
> avoid the warning. You my proposed change in the patch file.
>
> Regards Michael
> -- 
> Michael Bouschen		Tech@Spree Engineering GmbH
> mailto:mbo.tech@spree.de	http://www.tech.spree.de/
> Tel.:++49/30/235 520-33		Buelowstr. 66			
> Fax.:++49/30/2175 2012		D-10783 Berlin			
>
> maven-javadoc-plugin:report:
>     [mkdir] Created dir: D:\jdo\workspaces\jdo\trunk\api20\target 
> \javadoc\src
>     [javadoc] Generating Javadoc
>     [javadoc] Javadoc execution
>     [javadoc] Loading source files for package javax.jdo...
>     [javadoc] Loading source files for package javax.jdo.datastore...
>     [javadoc] Loading source files for package javax.jdo.identity...
>     [javadoc] Loading source files for package javax.jdo.listener...
>     [javadoc] Loading source files for package javax.jdo.spi...
>     [javadoc] Constructing Javadoc information...
>     [javadoc] Standard Doclet version 1.4.2_10
>     [javadoc] Generating D:\jdo\workspaces\jdo\trunk\api20\target 
> \docs\apidocs\constant-values.html...
>     [javadoc] Copying file D:\users\michael\.maven\cache\maven- 
> javadoc-plugin-1.7\plugin-resources\stylesheet.css to file D:\jdo 
> \workspaces\jdo\trunk\api20\target\docs\apidocs\stylesheet.css...
>     [javadoc] Building tree for all the packages and classes...
>     [javadoc] D:\jdo\workspaces\jdo\trunk\api20\src\java\javax\jdo 
> \FetchPlan.java:152: warning - The first sentence is interpreted to  
> be:
>     [javadoc] Generating D:\jdo\workspaces\jdo\trunk\api20\target 
> \docs\apidocs\javax\jdo\class-use\FetchPlan.html...
>     [javadoc] "Set the maximum fetch depth when fetching."
>     [javadoc] This sentence is different from what will be  
> interpreted as the first sentence in the
>     [javadoc] next major release (when that interpretation will be  
> internationalized), which is:
>     [javadoc] "Set the maximum fetch depth when fetching.
>     [javadoc]  0 has no meaning and will throw a JDOUserException"
>     [javadoc] To avoid this note, change the doc comment to make  
> this a proper first sentence, then
>     [javadoc] use -breakiterator from that point forward, which  
> will output this new sentence.
>     [javadoc] Building index for all the packages and classes...
>     [javadoc] D:\jdo\workspaces\jdo\trunk\api20\src\java\javax\jdo 
> \FetchPlan.java:152: warning - The first sentence is interpreted to  
> be:
>     [javadoc] Generating D:\jdo\workspaces\jdo\trunk\api20\target 
> \docs\apidocs\index-all.html...
>     [javadoc] "Set the maximum fetch depth when fetching."
>     [javadoc] This sentence is different from what would be  
> generated using -breakiterator:
>     [javadoc] "Set the maximum fetch depth when fetching.
>     [javadoc]  0 has no meaning and will throw a JDOUserException"
>     [javadoc] Building index for all classes...
>     [javadoc] D:\jdo\workspaces\jdo\trunk\api20\src\java\javax\jdo 
> \FetchPlan.java:152: warning - The first sentence is interpreted to  
> be:
>     [javadoc] Generating D:\jdo\workspaces\jdo\trunk\api20\target 
> \docs\apidocs\javax\jdo\FetchPlan.html...
>     [javadoc] "Set the maximum fetch depth when fetching."
>     [javadoc] This sentence is different from what would be  
> generated using -breakiterator:
>     [javadoc] "Set the maximum fetch depth when fetching.
>     [javadoc]  0 has no meaning and will throw a JDOUserException"
>     [javadoc] Generating D:\jdo\workspaces\jdo\trunk\api20\target 
> \docs\apidocs\help-doc.html...
>     [javadoc] 3 warnings
>     [delete] Deleting directory D:\jdo\workspaces\jdo\trunk\api20 
> \target\javadoc\src
> Index: src/java/javax/jdo/FetchPlan.java
> ===================================================================
> --- src/java/javax/jdo/FetchPlan.java	(revision 386408)
> +++ src/java/javax/jdo/FetchPlan.java	(working copy)
> @@ -141,8 +141,8 @@
>
>      /**
>       * Set the maximum fetch depth when fetching.
> -     * 0 has no meaning and will throw a JDOUserException.
> -     * -1 means that no limit is placed on fetching.
> +     * A value of 0 has no meaning and will throw a JDOUserException.
> +     * A value of -1 means that no limit is placed on fetching.
>       * A positive integer will result in that number of references  
> from the
>       * initial object to be fetched.
>       * @param fetchDepth the depth

Craig Russell
Architect, Sun Java Enterprise System http://java.sun.com/products/jdo
408 276-5638 mailto:Craig.Russell@sun.com
P.S. A good JDO? O, Gasp!