XML Automatic Documentation Tags
Recall that ...
In tutorial Automatic Documentation Generation in ASP.NET Applications we have explained to
you why it's hard to produce software documentation using the
traditional documentation schemes of Software Engineering.
We, then,
proposed a much more practical and super fast technique for
producing documentation by writing them within your source code and
then extracting them into a comprehensive and easy to read / browse
complete document.
In our previous work, we used Microsoft Visual Studio
2005 to extract the documentation from source code into an XML file.
We then worked out the procedure of how to feed this XML file to
NDOC to produce our complete documentation CHM file.
As you may recall, writing these documentation within
your source code needs a special syntax to be followed. We have
presented some brief information about the <summary> tag along with
some other elementary tags as well.
Here, in this tutorial, we will illustrate in more details how you can benefit from this
technique to the most extent by using some other recommended XML tags
to give more comprehensiveness and functionality to your final documentation
file.
The <summary>
tag
Usage: <summary>text</summary>
Use the summary tag to give an overall description about your class member. Summary
text is the only text that appears in the IntliSense feature. This tag is
generated automatically after you type the famous (''').
As an example about this tag see the following lines, then see the
final generated document in figure1.
| |
31 ''' <summary>
32 ''' This is summary of Function1
33 ''' </summary> |
|
Figure 1
The <remarks> tag
Used for listing the text under the remarks section of the final document. In this section you can give more supplementary information about your
class member, and details what is summarized in the <summary> section. This tag is
generated automatically.
As an example, see the following lines, then see the final document in
figure 2.
| |
10 ''' <remarks>
11 ''' More information about class1
12 ''' </remarks> |
|
Figure 2
The <c>, and
the <code> tags
Usage: <c>text</c>
The <c> tag identify that the text within it is source code. This tag is for
a single line of source code, use <code>text</code> to indicate
multiple lines of
source code.
The significance of those two tags is that if you wrote your code
directly inside any other tag without specifying then, then your
code will of course appear in the final documentation but will be
handled differently. For example, your code will be warped according
to the width of the window inside which it appears and this is of
course is an undesirable behavior.
The following lines give you an example about that. See the
final document in figure 3.
| |
2 ''' <summary>
3 ''' This is the summary of Class1
4 ''' Initialize the value of <c>var3 = false</c>
5 ''' Always test for the value of <c>var2</c>
6 ''' <code> if var2 is nothing then
7 ''' var2 = "Error.. var2 is an empty string"
8 ''' end if</code>
9 ''' </summary>
|
|
Figure 3
The <example> tag
Usage: <example>text</example>
The <example> tag gives you the ability to list an example describing how to use
a given class member in your code. It lists this under the Example section in the
final document.
Here's an example about this tag:
| |
15 ''' <summary>
16 ''' This is the summary of Sub1
17 ''' <example> This code sample shows you how to use this sub
18 ''' <code>
19 ''' dim p1 as integer = 5
20 ''' dim p2 as string = "This is a test"
21 ''' sub1(p1,p2)
22 ''' </code>
23 ''' </example>
24 ''' </summary>
|
|
The <exception> tag
Usage: <exception cref="XXX">text</exception>
The exception tag lists the exceptions that can be thrown by the
current method. The XXX is the exception complete qualification
reference. This must be a valid exception reference, and the compiler
will check the validity of the given reference within the working
environment. Note that XXX must be within double quotation marks (") .
As an example, see the following lines, then see the final document in
figure 4.
| |
38 ''' <exception cref="System.DivideByZeroException">
39 ''' This exception thrown when <c>parm2 = 0</c>
40 ''' </exception>
|
|
Figure 4
<param>
Usage: <param name="XXX">text</param>
This tag is used to list and describe the parameters of your method in the
method declaration section.
XXX is the name of the parameter, and it should come within double quotation marks
(").
The 'text' is the supplied description of the mentioned parameter. Note that the
<param name=".."> tag is generated automatically above the method declaration,
which means that you need not to write it yourself, you only need to write the
description.
As an example, see the following lines, then see the final document in
figure 5.
| |
27 ''' <param name="parm1">the first parameter</param>
28 ''' <param name="parm2">the second parameter</param>
|
|
Figure 5
The <returns>
tag
Usage: <returns>text</returns>
This tag is used to specify and describe the return value of a method or
property. This tag is always used above function declaration and is generated
automatically.
As an example, see the following lines, then see the final document in
figure 6.
| |
38 ''' <returns>
39 ''' This function returns an integer value
40 ''' </returns>
|
|
Figure 6
The <see> tag
Usage: <see cref="member"/>
Use this tag to specify a link to another member in your
application (like another function or class). You must supply a valid
member within the double quotation marks. The compiler will check
the validity of the supplied member.
As an example of how to use this tag, see the following lines, then
see the final document in figure 7.
| |
29 ''' <remarks>
30 ''' Call <see cref="Function1" />
31 ''' before calling this sub
32 ''' </remarks>
|
|
Figure 7
The <seealso> tag
Syntax: <seealso cref="member"/>
This tag do exactly as what <see> tag do, except the member of this
tag will be shown under the see also section in the final generated
document not within text as <see> tag do.
As an example, see the following lines, then see the final generated document in
figure 8.
| |
45 ''' <exception cref="System.DivideByZeroException">
46 ''' This exception thrown when <c>parm2 = 0</c>
47 ''' </exception>
48 ''' <seealso cref="Sub1"/>
|
|
Figure 8
<para>
Usage: <para>text</para>
This tag is useful when you want to structure your text into
paragraphs. The abbreviation 'para' stands for a paragraph. This tag can be used within
the
<summary>, the <remarks>, or the <return> tags to split the text
into paragraphs. This gives more readability to the final document.
As an example, see the following lines, then see the final document in
figure 9.
| |
10 ''' <remarks>
11 ''' More information about class1
12 ''' <para> paragraph number 1</para>
13 ''' <para> paragraph number 2</para>
14 ''' </remarks>
|
|
Figure 9
The <paramref> tag
Usage: <paramref name="paramName"/>
This tag is used to indicate that the word "paramName"
will be formatted as a parameter not as a normal word. The name of
the parameter you want to refer to must be enclosed within double
quotation marks.
As an example, see the following lines, then see the final document in
figure 10.
| |
46 ''' <remarks>
47 ''' The second input to this function
48 ''' <paramref name="parm2"/> must not be zero.
49 ''' </remarks>
|
|
Figure 10
The <permission> tag
Usage: <permission cref="member">text</permission>
This tag is used to specify what permissions are needed. The member must
be a valid class member or field within the current compilation
environment. The compiler will check for that. The text is the
description you will write to describe the situation. The
member must be enclosed by double quotation marks.
As an example, see the following lines, then see the final document in
figure 11.
| |
63 ''' <permission cref="System.Security.Permissions.FileIOPermission">
64 ''' Need to check the permission of the input file name.
65 ''' </permission>
|
|
Figure 11
The <list> tag
Usage:
<list type="type">
<listheader>
<term>term</term>
<description>text</description>
</listheader>
<item>
<term>term</term>
<description>text</description>
</item>
</list>
This tag is used to define a table or a definition list. The list can be
either bulleted list or numbered list.
Type can be "bullet" for bulleted list, or "number" for numbered list.
It can be "table" for a table of two columns.
The <listheader> block is used to specify the heading of the table or
the list. In case of the table type you have to supply the 'term' only.
The <item> block identifies an item within list or a row
inside the table.
You can supply both 'term' and 'description' for each item to create a
definition list, or you can supply only the description field for
bulleted list, numbered list, or table.
You can create as many <item> blocks as you need.
A final note, you can not include the <listheader> block if you do not want to
create a header for your list.
As an example, see the following lines that create a bulleted list,
then see the final document in figure 12.
| |
62 ''' <remarks>
63 ''' Before calling this function you have to call:
64 ''' <list type="bullet">
65 ''' <item>
66 ''' <term>Func1:</term>
67 ''' <description>function1</description>
68 ''' </item>
69 ''' <item>
70 ''' <term>Func2:</term>
71 ''' <description>function2</description>
72 ''' </item>
73 ''' </list>
74 ''' </remarks>
|
|
Figure 12
The following figures may give you some feelings about
the final generated document as a whole:
Figure 13
Figure 14 For further information
|
