[英]Adding an XML Documentation Comment file for a school project in Visual Code (C#)
我做了一个学校项目,我的老师稍后会检查。
我试图在一个插件的帮助下在 Visual Studio Code 中添加一些文档注释,该插件允许我编写///
自动生成 xml 代码。
我从Microsoft Docs about XML Documentation 中读到,你可以制作一个单独的 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>
它目前不起作用(它根本没有显示该方法的描述),我一直在为此苦恼。
这是直接在源代码文件中放置文档注释的替代方法。 通过将文档放在单独的文件中,您可以将源代码控制应用于与源代码分开的文档。 一个人可以签出源代码文件,其他人可以签出文档文件。
我确实理解这背后的动机,但是如果您决定使用单独的文件,则不能再使用 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>
如您所见,您需要为要记录的每个元素(类、方法、属性、构造函数、参数、返回类型等)学习特定的模式/语法。
声明:本站的技术帖子网页,遵循CC BY-SA 4.0协议,如果您需要转载,请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.