Question

让我们考虑以下源代码。

/// <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，例如，解决方案似乎使用单独的物理文件夹。

Answer 1

属性应该用作元数据装饰器（在有限的情况下，为特定的代码片段添加功能），并且不应该真正做出文档决策;这就是文档的用途。如果您有一个公开API的库，那么您应该为API本身使用Facade类，它可以（并且可能应该）位于不同的文件夹中。从该文件夹生成doc，你很高兴。此外，通过分离问题，它将为您节省很多麻烦。

使用C＃属性和文档

1 个答案: