ch3-XML Documentation

Chapter_3     ch3-LongNames                                                             ch3-Application 

Contents:

Exercise_3-12     Exercise_3-13     Exercise_3-14

Exercise 3-12     TCS, p. 86

Exercise 3-12. Find the code for the second version of HelloDate.cs, which is the simple comment documentation example. Execute csc /doc (or equivalent) on the file and view the results with your XML-aware Web browser.

HelloDate.cs     TCS, p. 82-83

///<summary>Shows doc comments</summary>

///<remarks>The documentation comments within C#

///are remarkably useful, both within the Visual

///Studio environment and as the basis for more

///significant printed documentation.</remarks>

public class HelloDate

{

  ///<summary>Entry point</summary>

  ///<remarks>Prints greeting to

  /// <paramref name="args[0]"/>, gets a

  /// <see cref="System.DateTime">DateTime</see>

  /// and subsequently prints it.</remarks>

  ///<param name="args">Command-line should have a

  ///single name. All other args will be ignored.

  ///</param>

  public static void Main(string[] args)

  {

    System.Console.Write("Hello, {0}. It's: ", args[0]); // no newline

    System.Console.WriteLine(System.DateTime.Now);

    // System.Console.WriteLine(System.DateTime.Now.ToString());

  }

}

/*

mcs HelloDate.cs

mono HelloDate.exe // exception (run-time error)

mono HelloDate.exe James

Hello, James. It's: 7/21/2023 11:05:05 AM

mono HelloDate.exe John Doe

Hello, John. It's: 7/21/2023 11:05:47 AM

mcs -doc:HelloDate.xml HelloDate.cs

*/

Note:  Compare with the original version of HelloDate.cs.

*****************************************************************************************

*****************************************************************************************

*****************************************************************************************

HelloDate.xml     TCS, p. 83-84 

<?xml version="1.0"?>

<doc>

    <assembly>

        <name>HelloDate</name>

    </assembly>

    <members>

        <member name="T:HelloDate">

            <summary>Shows doc comments</summary>

            <remarks>The documentation comments within C#

            are remarkably useful, both within the Visual

            Studio environment and as the basis for more

            significant printed documentation.</remarks>

            </member>

        <member name="M:HelloDate.Main(System.String[])">

            <summary>Entry point</summary>

            <remarks>Prints greeting to

             <paramref name="args[0]" />, gets a

             <see cref="T:System.DateTime">DateTime</see>

             and subsequently prints it.</remarks>

            <param name="args">Command-line should have a

            single name. All other args will be ignored.

            </param>

            </member>

    </members>

</doc>

*****************************************************************************************

*****************************************************************************************

*****************************************************************************************

*****************************************************************************************

*****************************************************************************************

Exercise 3-13     TCS, p. 86

Exercise 3-13. Add an HTML list of items to the documentation in Exercise_3-12.

HelloDate.cs

///<summary>Shows doc comments</summary>

///<remarks>The documentation comments within C#

///are remarkably useful, both within the Visual

///Studio environment and as the basis for more

///significant printed documentation.</remarks>

///<list type="bullet">

///<listheader>

///<term>List</term>

///<description>List of items</description>

///</listheader>

///<item>

///<term>Item 1</term>

///<description>Desciption of item 1</description>

///</item>

///<item>

///<term>Item 2</term>

///<description>Desciption of item 2</description>

///</item>

///</list>

public class HelloDate

{

  ///<summary>Entry point</summary>

  ///<remarks>Prints greeting to

  /// <paramref name="args[0]"/>, gets a

  /// <see cref="System.DateTime">DateTime</see>

  /// and subsequently prints it.</remarks>

  ///<param name="args">Command-line should have a

  ///single name. All other args will be ignored.

  ///</param>

  public static void Main(string[] args)

  {

    System.Console.Write("Hello, {0}. It's: ", args[0]); // no newline

    System.Console.WriteLine(System.DateTime.Now);

    // System.Console.WriteLine(System.DateTime.Now.ToString());

  }

}

/*

mcs HelloDate.cs

mono HelloDate.exe // exception (run-time error)

mono HelloDate.exe James

Hello, James. It's: 7/21/2023 11:05:05 AM

mono HelloDate.exe John Doe

Hello, John. It's: 7/21/2023 11:05:47 AM

mcs -doc:HelloDate.xml HelloDate.cs

*/

*****************************************************************************************

*****************************************************************************************

*****************************************************************************************

HelloDate.xml

<?xml version="1.0"?>

<doc>

    <assembly>

        <name>HelloDate</name>

    </assembly>

    <members>

        <member name="T:HelloDate">

            <summary>Shows doc comments</summary>

            <remarks>The documentation comments within C#

            are remarkably useful, both within the Visual

            Studio environment and as the basis for more

            significant printed documentation.</remarks>

            <list type="bullet">

            <listheader>

            <term>List</term>

            <description>List of items</description>

            </listheader>

            <item>

            <term>Item 1</term>

            <description>Desciption of item 1</description>

            </item>

            <item>

            <term>Item 2</term>

            <description>Desciption of item 2</description>

            </item>

            </list>

            </member>

        <member name="M:HelloDate.Main(System.String[])">

            <summary>Entry point</summary>

            <remarks>Prints greeting to

             <paramref name="args[0]" />, gets a

             <see cref="T:System.DateTime">DateTime</see>

             and subsequently prints it.</remarks>

            <param name="args">Command-line should have a

            single name. All other args will be ignored.

            </param>

            </member>

    </members>

</doc>

*****************************************************************************************

*****************************************************************************************

*****************************************************************************************

*****************************************************************************************

*****************************************************************************************

Exercise 3-14     TCS, p. 86

Exercise 14. Take the program in Exercise_3-1 and add comment documentation to it. Extract this comment documentation and view it with your Web browser.

Hello.cs

///<summary>Main (and only) class of the greeting program</summary>

///<remarks>The first program anyone is supposed to write

///when starting to learn a new programming language</remarks>

public class Hello

{

///<summary>Entry point to the program</summary>

///<remarks>Prints a greeting message, <pre>Hello, world!</pre>

///</remarks>

  public static void Main()

  {

    System.Console.WriteLine("Hello, world!");

  }

}

/*

mcs Hello.cs

mono Hello.exe

Hello, world!

mcs -doc:Hello.xml Hello.cs

*/

*****************************************************************************************

*****************************************************************************************

*****************************************************************************************

Hello.xml

<?xml version="1.0"?>

<doc>

    <assembly>

        <name>Hello</name>

    </assembly>

    <members>

        <member name="T:Hello">

            <summary>Main (and only) class of the greeting program</summary>

            <remarks>The first program anyone is supposed to write

            when starting to learn a new programming language</remarks>

            </member>

        <member name="M:Hello.Main">

            <summary>Entry point to the program</summary>

            <remarks>Prints a greeting message, <pre>Hello, world!</pre>

            </remarks>

            </member>

    </members>

</doc>

Chapter_3     ch3-LongNames                                            Back_to_Top                                            ch3-Application