使用 C# 属性和文档答案

【问题标题】：Using C# Attributes and documentation使用 C# 属性和文档
【发布时间】：2011-08-23 06:53:01
【问题描述】：

让我们考虑以下源代码。

/// <summary>
/// This is a method I would like to document
/// </summary>
/// <param name="param1">Description for param1</param>
/// <param name="param2">Description for param2</param>
/// <returns>See Type1</returns>
[Api(1)]
public Type1 Method1(
    [ApiParam(Name = Names.Name1, IsRequired = true)] string param1
     string param2
    ) {
    ...
    }

/// <summary>
/// This is a method I would like NOT to document
/// </summary>
public void Method2() {
    ...
    }

我的问题是你们如何处理代码经常使用 C# 属性但文档生成工具似乎不支持它们的事实。

在上面的例子中，我想生成帮助文件，它只包含用 ApiAttribute 标记的方法（和类型）。例如。

例如，对于 Doxygen，该解决方案似乎使用单独的物理文件夹。

【问题讨论】：

任何公开可见的都是 API，遗憾的是，您不能说“我知道这是可公开访问的，但它不是 API 的一部分”

标签： c# documentation doxygen

【解决方案1】：

属性应该用作元数据装饰器（并且在有限的情况下为特定的代码片段添加功能），并且不应该真正对文档做出决定；这就是文档的用途。如果您有一个公开 API 的库，您应该使用 API 本身的外观类，它可以（并且可能应该）在不同的文件夹中。从该文件夹中生成文档，您就可以开始了。此外，它还可以通过分离关注点为您省去很多麻烦。

【讨论】：