在 Visual Code (C#) 中为学校项目添加 XML 文档注释文件

Question

I have made a school project that my teacher will check later on.

I am trying to add some Documentation Comments in Visual Studio Code with the help of a plugin that allows me to write /// which makes the xml code automatically.

I have read from the Microsoft Docs about XML Documentation that you can make a seperate XML file rather than clutter the code with comments but i have been having a hard time getting it to work.

Here is an example:

 ///<include file='docs.xml' path='docs/members[@name="program"]/Select/*'/>
        public static bool Select (ConsoleKey input) {
            ConsoleKeyInfo key = Console.ReadKey (true);
            if (key.Key == input) {
                return true;

            }
            return false;
        }

This is what the doc.xml file has about this method:

 <doc>
  <members name="program">
    <Select>
        <summary>
        Summarizes a way to detect <paramref name ="input"/>.
        </summary>
        <returns>
        true when <paramref name = "input"/> is detected. 
        </returns>
        <param name="input"> Checks what key it should detect.</param>
        <example>
        <code>

            string outputToConsole = "Hello World!";
            void Main () {
                if (Selecting.Select (ConsoleKey.Spacebar)) {
                   Console.WriteLine (outputToConsole);
          //Prints "Hello World" when key "Spacebar" is pressed!
                }
            }

        </code>
      </example>
    </Select>

It currently does not work (It does not show a description on the method at all) and i have been racking my head over this.

Answer 1

The documentation says (emphasis mine):

This is an alternative to placing documentation comments directly in your source code file. By putting the documentation in a separate file, you can apply source control to the documentation separately from the source code . One person can have the source code file checked out and someone else can have the documentation file checked out.

I do understand the motivation behind this, but if you decide to use a separate file you can no longer use Visual Studio autocomplete/intellisense to generate the XML elements for you, and you'll need to learn the schema/syntax of the XML documentation file .

Also, as the assembly gets bigger, so will the XML file. In the real world this file could have 1000s of lines of code. From a maintenance and source control perspective, I'd rather have the documentation in the c# source files. I honestly think it's not worth the trouble.

Anyway, if you still want to use the external files there are a few tricks you can use.

Consider a class library named FileDemo . Righ-click the project > Properties > Build and then tick the checkbox XML Documentation File :

This will generate the XML documentation file on build:

And now the funny part. As I mentioned before, the XML documentation file has a particular syntax you'll need to learn. The best way to do it is to add some XML documentation to existing classes, methods etc and check the generated XML. For example, considering the following namespaces and classes:

namespace FileDemo

namespace FileDemo
{
    /// <summary>
    /// This is a class
    /// </summary>
    public class Class1
    {
        /// <summary>
        /// Does nothing
        /// </summary>
        /// <param name="text">Just some text</param>
        public void DoNothing(string text)
        {

        }
    }

        /// <summary>
    /// This is another class
    /// </summary>
    public class Class2
    {
        /// <summary>
        /// Bla bla
        /// </summary>
        /// <param name="text">Just some text</param>
        public void DoSomething(string text)
        {

        }
    }
}

namespace FileDemo.AnotherNamespace

namespace FileDemo.AnotherNamespace
{
    /// <summary>
    /// Yet another class
    /// </summary>
    public class Class3
    {
        /// <summary>
        /// Gets or sets something
        /// </summary>
        public string Foo { get; set; }

        /// <summary>
        /// Creates a new instance of <see cref="Class3"/>
        /// </summary>
        public Class3()
        {

        }

        /// <summary>
        /// This method is supposed to calculate something
        /// </summary>
        /// <param name="firstValue">First value</param>
        /// <param name="secondValue">Second value</param>
        /// <returns>The result of the calculation</returns>
        public int Calculate(int firstValue, int secondValue)
        {
            return 1;
        }
    }
}

After building the project, the generated documentation file is the following:

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>FileDemo</name>
    </assembly>
    <members>
        <member name="T:FileDemo.AnotherNamespace.Class3">
            <summary>
            Yet another class
            </summary>
        </member>
        <member name="P:FileDemo.AnotherNamespace.Class3.Foo">
            <summary>
            Gets or sets something
            </summary>
        </member>
        <member name="M:FileDemo.AnotherNamespace.Class3.#ctor">
            <summary>
            Creates a new instance of <see cref="T:FileDemo.AnotherNamespace.Class3"/>
            </summary>
        </member>
        <member name="M:FileDemo.AnotherNamespace.Class3.Calculate(System.Int32,System.Int32)">
            <summary>
            This method is supposed to calculate something
            </summary>
            <param name="firstValue">First value</param>
            <param name="secondValue">Second value</param>
            <returns>The result of the calculation</returns>
        </member>
        <member name="T:FileDemo.Class1">
            <summary>
            This is a class
            </summary>
        </member>
        <member name="M:FileDemo.Class1.DoNothing(System.String)">
            <summary>
            Does nothing
            </summary>
            <param name="text">Just some text</param>
        </member>
        <member name="T:FileDemo.Class2">
            <summary>
            This is another class
            </summary>
        </member>
        <member name="M:FileDemo.Class2.DoSomething(System.String)">
            <summary>
            Bla bla
            </summary>
            <param name="text">Just some text</param>
        </member>
    </members>
</doc>

As you can see, there is a particular schema/syntax that you need to learn for each element you're trying to document (classes, methods, properties, constructors, parameters, return types, etc).