是否有用于注释 C# 代码的标准（如 phpdoc 或 python 的文档字符串）？

Posted 2023-02-21

【中文标题】是否有用于注释 C# 代码的标准（如 phpdoc 或 python 的文档字符串）？

【英文标题】：Is there a standard (like phpdoc or python's docstring) for commenting C# code?

【发布时间】：2010-09-07 06:20:39

【问题描述】：

是否有用于注释 C# 代码的标准约定（如 phpdoc 或 python 的 docstring），以便可以从源代码自动生成类文档？

【参考方案1】：

C# 已内置documentation commands 玩得开心！

【讨论】：

很遗憾，此链接已过期

【参考方案2】：

我总是被告知要使用以 2 个或更多星号打开的块 cmets 来分隔文档 cmets。

/**
Documentation goes here.
(flowerboxes optional) 
*/

【参考方案3】：

前面的答案完美地指出了 XML 语法。我只是想提出我对解析项目中所有 cmets 的 free (and open-source) nDoc help library generator 的建议。

【参考方案4】：

Microsoft 使用“XML Documentation Comments”，它将提供 IDE 智能感知描述，如果您打开 XML 文件输出的生成，还允许您使用 Sandcastle 等工具自动生成 MSDN 样式的文档。

要打开生成文档的 XML 文件，请右键单击 Visual Studio 中的项目，单击“属性”并转到“构建”选项卡。您可以在底部指定 XML cmets 输出文件的位置。

【参考方案5】：

您可以使用 XML 样式的 cmets，并使用工具将这些 cmets 提取到 API 文档中。

这里是评论风格的一个例子：

/// <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，它提供了一个快捷键来自动为类或方法生成 cmets。 Sandcastle，从 XML cmets 生成 MSDN 风格的文档。

【讨论】：

有关沙堡的更多信息，请参阅***.com/questions/319632/…。

我在哪里提到参数的类型和返回类型？

【参考方案6】：

/// <summary>
///
/// </summary>
/// <param name="strFilePath"></param>

http://msdn.microsoft.com/en-us/magazine/cc302121.aspx

【讨论】：

如果我点击这个链接，我最终会来到这里...microsoft.com/en-us/download/details.aspx?id=55979