使用C＃属性和文档 [英] Using C# Attributes and documentation

问题描述

我们来考虑以下源代码。

Let's consider the following source code.

/// <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＃属性，但文档生成工具似乎不支持它们。

My question is how do you guys deal with the fact that the code often uses C# attributes but documentation generate tools seem not support them.

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

In the above example I would like to generate help file(s) which would include only methods (and types) which are marked with the ApiAttribute. For example.

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

For Doxygen, for example, the solution seems to use separate physical folders.

推荐答案

属性应该用作元数据装饰器（在有限的情况下，将功能添加到特定代码段），并且不应该真正做出文档的决策;这就是文档。如果您有一个暴露API的库，那么您应该为API本身使用外观类，这可以（也可能应该）在另一个文件夹中。从该文件夹生成文档，你很好。此外，它会通过分离问题为您节省很多头痛。

Attributes should be used as a metadata decorator (and in limited cases add functionality to specific pieces of code), and shouldn't really be making decisions on documentation; that's what documentation is for. If you have a library that exposes an API, you should be using facade classes for the API itself, which can (and likely should) be in a different folder. Generate the doc off that folder, and you're good to go. Plus it will save you a lot of headache by separating concerns.

这篇关于使用C＃属性和文档的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！