Home
    Shop
    Advertise
    Write For Us
    Affiliate
    Newsletter
    Contact

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

 
   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


Tutorial toolbar:  Tell A Friend  |  Add to favorites  |  Feedback  |   


comments powered by Disqus