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

Question

我做了一个学校项目，我的老师稍后会检查。

我正在尝试借助 plugin 在 Visual Studio Code 中添加一些文档注释，它允许我编写 /// 自动生成 xml 代码。

我从Microsoft Docs 中读到了关于 XML 文档的内容，您可以制作一个单独的 XML 文件，而不是用 cmets 将代码弄得乱七八糟，但我一直很难让它工作。

这是一个例子：

 ///<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;
        }

这是 doc.xml 文件中关于此方法的内容：

 <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>

它目前不起作用（它根本没有显示关于方法的描述），我一直在为此绞尽脑汁。

Answer 1

文档说（强调我的）：

这是将文档 cmets 直接放在源代码文件中的替代方法。 通过将文档放在单独的文件中，您可以将源代码控制与源代码分开应用到文档。一个人可以签出源代码文件，其他人可以签出文档文件。

我确实理解这背后的动机，但是如果您决定使用单独的文件，您将无法再使用 Visual Studio 自动完成/智能感知为您生成 XML 元素，您需要学习架构/XML 文档文件的语法。

此外，随着程序集变大，XML 文件也会变大。在现实世界中，这个文件可能有 1000 行代码。从维护和源代码控制的角度来看，我宁愿将文档放在 c# 源文件中。老实说，我认为这不值得麻烦。

无论如何，如果您仍想使用外部文件，您可以使用一些技巧。

考虑一个名为FileDemo 的类库。右击项目 > Properties > Build 然后勾选复选框XML Documentation File：

这将在构建时生成 XML 文档文件：

现在是有趣的部分。正如我之前提到的，XML 文档文件具有您需要学习的特定语法。最好的方法是将一些 XML 文档添加到现有的类、方法等并检查生成的 XML。例如，考虑以下命名空间和类：

命名空间文件演示

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)
        {

        }
    }
}

命名空间 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;
        }
    }
}

构建项目后，生成的文档文件如下：

<?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>

如您所见，您需要为尝试记录的每个元素（类、方法、属性、构造函数、参数、返回类型等）学习特定的架构/语法。