关于注释:是否有用于注释C#代码的标准(例如phpdoc或python \\的docstring)?

关于注释:是否有用于注释C#代码的标准(例如phpdoc或python \\的docstring)?

Is there a standard (like phpdoc or python's docstring) for commenting C# code?

是否存在用于注释C#代码的标准约定(例如phpdoc或python的docstring),以便可以从源代码自动生成类文档?


您可以使用XML样式注释,并使用工具将这些注释提取到API文档中。

以下是评论样式的示例:

1
2
3
4
5
6
7
8
9
10
11
12
/// <summary>
/// Authenticates a user based on a username and password.
/// </summary>
/// <param name="username">The username.</param>
/// <param name="password">The password.</param>
/// <returns>
/// True, if authentication is successful, otherwise False.
/// </returns>
/// <remarks>
/// For use with local systems
/// </remarks>
public override bool Authenticate(string username, string password)

一些有助于实现此目的的项目是:

GhostDoc,它提供了一个快捷键,可以自动为类或方法生成注释。
Sandcastle,它从XML注释生成MSDN样式文档。


1
2
3
4
/// <summary>
///
/// </summary>
/// <param name="strFilePath"></param>

http://msdn.microsoft.com/zh-cn/magazine/cc302121.aspx


前面的答案完美地指出了XML语法。我只是想提出免费(开源)nDoc帮助库生成器的建议,该生成器可解析项目中的所有注释。


Microsoft使用" XML文档注释",它将提供IDE智能感知描述,并且如果您打开XML文件输出的生成功能,还允许您使用诸如Sandcastle之类的工具自动生成MSDN样式的文档。 >

要打开用于文档的XML文件的生成,请右键单击Visual Studio中的项目,单击"属性",然后转到"构建"选项卡。在底部,您可以为XML注释输出文件指定位置。


我总是被告知要使用带有两个或更多星号的块注释来分隔文档注释。

1
2
3
4
/**
Documentation goes here.
(flowerboxes optional)
*/

C#内置了文档命令
玩得开心!


推荐阅读