Win a copy of The Little Book of Impediments (e-book only) this week in the Agile and Other Processes forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Question about javadoc

 
Eric Kim
Ranch Hand
Posts: 37
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
A quick question about javadoc.
I am preparing for SCJD assign and come accross an issue with javadoc.
Here is the comment I wrote for one of the utility function
/**
* Get the number of occurance of string test
* example:
* getCount( "This test will demo how to use javadoc. run this test as javadoc *.java.", "test");
* This function call should return 2 as there are two "test" occurances.
*
* @param strValue input string to search
* @param strKeyword keyword to search in input string
* @return the number of occurance as integer
*/
public static int getCount( String strValue, String strKeyword )
{
intnIndex = 0;
intnCount = 0;
intnPos;
while( ( nPos = strValue.indexOf( strKeyword, nIndex ) ) > 0 )
{
nCount++;
nIndex += nPos + strKeyword.length();
}
return nCount;
}
while directory run javadoc it will complaints multiple lines comments. So I have to run it in this way:
javadoc -breakiterator *.java
This time there is no warning. But generated comment does not look right:
In the method summary table, here is what I get:
static int getCount(java.lang.String strValue, java.lang.String strKeyword)
Get the number of occurance of string test example: getCount( "This test will demo how to use javadoc. run this test as javadoc *.java
Some comments are truncated.

In the method details section, it does not look right either:
getCount
public static int getCount(java.lang.String strValue,
java.lang.String strKeyword)Get the number of occurance of string test example: getCount( "This test will demo how to use javadoc. run this test as javadoc *.java.", "test"); This function call should return 2 as there are two "test" occurances.
Parameters:
strValue - input string to search
strKeyword - keyword to search in input string
Returns:
the number of occurance as integer
It puts everything as one line, which looks ugly.
Is there any quick way to work around? I guess adding some HTML tag might be solution, can someone suggest how should I add those?
Thanks
eric
 
Mogens Nidding
Ranch Hand
Posts: 77
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
This advice should help:
  • Put a period after the first sentence. Everything before the first period gets in the javadoc summary.
  • Basically, your javadoc comments are HTML where linebreaks usually have no effect. If you feel you must include a line break, use <br>. To make a new paragraph, <p>.
  • Since you are writing HTML, I guess that strictly speaking, you should escape " as &quot;, < as &lt; and > as &gt;, although I'm not 100% sure this is necessary.
  • How to Write Doc Comments for the Javadoc Tool is a great place to find javadoc answers.


  • Try this:

    Hope this helps!
    [ March 12, 2004: Message edited by: Nicky Bodentien ]
    [ March 12, 2004: Message edited by: Nicky Bodentien ]
     
    George Marinkovich
    Ranch Hand
    Posts: 619
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Hi Eric,
    Welcome to this forum.
    In javadoc the first sentence of a javadoc comment is special. It is used to generate the summary description of the item being commented. As such it should stand alone. In other words, if you were to see only this first sentence in a summary description it should make sense without reference to the sentences (if any) that follow. Javadoc defines a sentence as ending in some sentence-ending punctuation, such as period (.), question mark (?), or exclamation mark (!). So in your example, the first sentence is "Get the number... occurrences." That's probably not what you intended. I imagine you want a first sentence such as: "Gets the number of occurrences of the keyword in the value."
    I usually leave a blank line after the first sentence of a javadoc comment to remind myself that the first sentence is special:

    Please use the Instant UUB Codes at the bottom of the "Post a Reply" editor. If you surround your code with CODE tags then it will retain it's formatting and be easier for everyone to read.
    If you follow the advice about terminating the first sentence with end-of-sentence punctuation then I don't think you'll need the -breakiterator switch (I didn't use it) and then I think the generated javadoc will look the way you expect.
    One other thing, within you javadoc comment if you want to give an example of method usage (a very good thing to do in my opinion) then enclose such a usage example within <pre> and </pre> codes. They will cause the enclosed text to retain it's original formatting, so that it will look like you want it to, rather than how the javadoc formatter thinks it should.
     
    Eric Kim
    Ranch Hand
    Posts: 37
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Thanks a lot!
     
    • Post Reply
    • Bookmark Topic Watch Topic
    • New Topic