Summary and Description

• @summary - for explicit summary section
• @desc - for explicit description (not part of summary) section
• @untaggedText - for the (optional) initial text section not marked with any @-tag.

{:This is a nice DocComment. Here is sentence two.}

When processing this, Time2HELP first "transforms" it into:

{:@untaggedText This is a nice DocComment. Here is sentence two.}

Note

@untaggedText is only a "virtual" @-tag, you should never use it yourself.

Then T2H checks if there are any explicit @desc tag inside this DocComment, if so, @untaggedText gets transformed into @summary.

Example
Time2HELP internally transforms

{:This Component handles e.g. dates and stuff. @desc It's not very good though. }

into

{:@summary This Component handles e.g. dates and stuff. @desc It's not very good though. }

If there are no @summary tag nor @desc tag in the DocComment, T2H splits the @untaggedText into a @summary and @desc automatically, by looking for the end of the first sentence.

It treats:

{:This Component handles dates and stuff. It's not very good though. }

as equivalent to:

{:@summary This Component handles dates and stuff. @desc It's not very good though. }

Beware that

{:This Component handles e.g. dates and stuff. It's not very good though. }

is transformed into

{:@summary This Component handles f. @desc i. dates and stuff. It's not very good though. }

because it splits the @summary at the first ".". To handle this properly, use:

{:This Component handles e.g. dates and stuff. @desc It's not very good though. }

If all you want is a summary, and it does contain a ".", you should use

{:@summary This Component handles e.g. dates and stuff.}

or (as discussed below, use the equivalent "$" shortcut):

{:$ This Component handles e.g. dates and stuff.}

Shortcuts
At the start of the DocComment, T2H supports two "shortcuts". If the first text of the "real" part of the DocComment starts with a ":", then ":" is a shortcut for @desc.

This means that

{::This is description, not summary}

is treated equivalently to

{:@desc This is description, not summary}

The second shortcut is the @summary shortcut, "$". This is useful if you have no explicit @desc in your DocComment, but still want multiple sentences in your summary, or your summary contains a false "summary terminator", like "e.g." etc.

{:$This is a summary. It contains multiple sentences.}