是否有用于注释 C# 代码的标准(如 phpdoc 或 python 的文档字符串)?

Posted

技术标签:

【中文标题】是否有用于注释 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

以上是关于是否有用于注释 C# 代码的标准(如 phpdoc 或 python 的文档字符串)?的主要内容,如果未能解决你的问题,请参考以下文章

PHP如何优雅地在PHP里写注释 | PHP的注释PHPDoc

PHP如何优雅地在PHP里写注释 | PHP的注释PHPDoc

如何使用 PHP 解析 phpDoc 样式的注释块?

PHPDoc & Psalm - 注释一个“类数组”

用于可变长度参数数组的 PHPDoc

正则表达式去除 phpdoc 多行注释