Menu
javadoc uses the first "sentence" of a doc comment as a summary sentence. It assumes that a period followed by a space, tab, or line terminator ends the sentence. Suppose I want an abbreviation like "e.g." or "etc." in my summary; is there a way to tell javadoc not to treat it as the end of a sentence? I can replace the period with . but I'm wondering if there's a less ugly way.
649
Writing Javadoc Comments In general, Javadoc comments are any multi-line comments (" /** ... */ ") that are placed before class, field, or method declarations. They must begin with a slash and two stars, and they can include special tags to describe characteristics like method parameters or return values.
Javadoc scans your source files looking for documentation comments, also known as “Javadoc comments”. They begin with /** (two stars) and end with */ (one star).
Generally, the first sentence of Javadoc should give a brief description of the class/method/field. Then the full description should follow. And if you want to include any notes, a specialized paragraph with a "Note:" prepended should suffice. Generally if you open (xml-)tags you should close them somewhere.
Fortunately, all modern versions of the JDK provide the Javadoc tool – for generating API documentation from comments present in the source code.
It's best to avoid periods in the first sentence. In How to Write Doc Comments for the Javadoc Tool it's suggested that you should replace the space character as a workaround:
/** * This is a simulation of Prof. Knuth's MIX computer. */ /** * This is a simulation of Prof.<!-- --> Knuth's MIX computer. */
Personally, I would just omit the dot if I couldn't avoid abbreviations altogether.
83
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
