If you run pasdoc with --auto-abstract CommandLine option, pasdoc will automatically deduce the abstract description of every item from the first sentence of it’s description. This means that you can write

and it’s equivalent to

This means that you can avoid writing explicitly @abstract tags, which means that your comments look less cluttered. Of course, this also means that you have to carefully watch to make the first sentence of every description to "stand on it’s own".

This is a standard feature of javadoc, and it’s also available in doxygen.

The parsing logic is simple: the first sentence of the description ends at the first period followed by any whitespace (including newline). Of course this period must be in the "top-level" text, not inside parameter of any @-tag. If there is no such period in the description, then the whole description is treated as one sentence, and the whole description is treated as an abstract description of the item.

Of course if any description has an explicit @abstract section, then this has priority over "the first sentence rule". Using explicit @abstract tag may be useful if e.g. you need to make the abstract description two-sentence long.

Note that there is actually a small difference between two examples given above. It occurs when pasdoc writes full description of a given item (full = abstract one + the rest).

If you used explicit @abstract tag, then pasdoc will always separate the abstract description with some space (e.g. paragraph marker, <p>, in HTML) from the rest of the description. But if your abstract description was deduced automatically, then pasdoc will not automatically insert such paragraph. This way full description of an item looks more like it was specified in source code.

So if I would really want to make two exactly equivalent examples, I should show this as the first example (note that I explicitly inserted empty line between abstract description and the rest here):

See test unit of this feature.