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

时间:2018-10-23 09:38:10

标签: c# xml xml-parsing visual-studio-code

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

我试图借助plugin在Visual Studio Code中添加一些文档注释,该注释使我可以编写///来自动生成xml代码。

我从Microsoft Docs中读到了有关XML文档的信息,您可以制作一个单独的XML文件,而不用使注释变得混乱,但是我一直很难使它工作。

这里是一个例子:

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

它目前不起作用(它根本没有显示该方法的描述),我一直对此表示怀疑。

1 个答案:

答案 0 :(得分:1)

文档说(重点是我):

  

这是将文档注释直接放置在源代码文件中的一种替代方法。 通过将文档放在单独的文件中,您可以将源代码管理与源代码分开应用。一个人可以签出源代码文件,其他人可以签出文档文件。

我确实了解其背后的动机,但是如果您决定使用单独的文件,您将无法再使用Visual Studio自动完成/智能来为您生成XML元素,并且您将需要学习架构/ XML文档文件的语法

此外,随着程序集的变大,XML文件也将变大。在现实世界中,此文件可能包含数千行代码。从维护和源代码管理的角度来看,我宁愿将文档放在c#源文件中。老实说,我认为这是不值得的。

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

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

Project properties

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

Solution Explorer

现在有趣的部分。如前所述,XML文档文件具有您需要学习的特定语法。最好的方法是将XML文档添加到现有的类,方法等中,并检查生成的XML。例如,考虑以下命名空间和类:

命名空间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)
        {

        }
    }
}

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

如您所见,对于要记录的每个元素(类,方法,属性,构造函数,参数,返回类型等),都需要学习一个特定的架构/语法。