Using C# Attributes and documentation

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.

Anything that's publicly visible is the API, unfortunately you don't get to say "I know this is publicly accessible but it's not part of the API" — MattDavey
– MattDavey, Commented Aug 23, 2011 at 7:59

drharris · Accepted Answer · 2011-08-23 07:02:19Z

2

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.

answered Aug 23, 2011 at 7:02

drharris

11.2k5 gold badges46 silver badges56 bronze badges

Sign up to request clarification or add additional context in comments.

Collectives™ on Stack Overflow

Using C# Attributes and documentation

1 Answer 1

Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related