我做了一个学校项目,我的老师以后会检查。
我试图借助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>
它目前不起作用(它根本没有显示该方法的描述),我一直对此表示怀疑。
答案 0 :(得分:1)
这是将文档注释直接放置在源代码文件中的一种替代方法。 通过将文档放在单独的文件中,您可以将源代码管理与源代码分开应用。一个人可以签出源代码文件,其他人可以签出文档文件。
我确实了解其背后的动机,但是如果您决定使用单独的文件,您将无法再使用Visual Studio自动完成/智能来为您生成XML元素,并且您将需要学习架构/ XML文档文件的语法。
此外,随着程序集的变大,XML文件也将变大。在现实世界中,此文件可能包含数千行代码。从维护和源代码管理的角度来看,我宁愿将文档放在c#源文件中。老实说,我认为这是不值得的。
无论如何,如果您仍然想使用外部文件,则可以使用一些技巧。
考虑一个名为FileDemo
的类库。右键单击项目> Properties
> Build
,然后勾选复选框XML Documentation File
:
这将在构建时生成XML文档文件:
现在有趣的部分。如前所述,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>
如您所见,对于要记录的每个元素(类,方法,属性,构造函数,参数,返回类型等),都需要学习一个特定的架构/语法。