8.4. Documentation Comments

Commenting the Source Code.  You can include documentation comments in the agent description files, ahead of declarations for any agent, capability, plan, goal, event or expression, etc. You can also create comments for each package and another one for the overview, though their syntax is slightly different. The comments in the agent description files are regular xml-comments consisting of the characters between the characters <!-- that begin the comment and the characters --> that end it. The text in a comment can continue onto multiple lines.

<!--
    This is the typical format of a simple documentation
    comment that spans multiple lines.
-->

<!-- To save space you can also put a comment on one line. -->

Placement of comments.  Documentation comments are recognized only when placed immediately before agent, capability, belief, goal, plan, event or expression declarations. Only one documentation comment per declaration statement is recognized by the Jadexdoc tool.

<!-- This is the comment for the agent 'MyAgent' -->
<agent name="MyAgent" package="jadex.examples.myagents">
    <beliefs>
        <!-- The comment for the belief 'MyBelief' -->
        <belief name="MyBelief" class="Object"/>
    </beliefs>
</agent>		

Comments are written in HTML.  The texts can be written in HTML, in that they should use HTML entities and can use HTML tags. You can use whichever version of HTML your browser supports. The bold HTML tag <b> is shown in the following example.

<!-- This is a <b>documentation</b> comment. -->

First sentence.  The first sentence of each documentation comment should be a summary sentence, containing a concise but complete description of the declared member. This sentence ends at the first period that is followed by a blank, tab, or line terminator. The Jadexdoc tool copies this first sentence to the member summary at the top of the HTML page. For convenience, Jadexdoc strips any html tags from this sentence, when it is displayed in a summary table.