Question

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() {
    ...
    }

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.

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.

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

Answer 1

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.