使用 C# 属性和文档
让我们考虑以下源代码。
/// <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，解决方案似乎使用单独的物理文件夹。
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.
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（1）
属性应该用作元数据装饰器（并且在有限的情况下向特定代码段添加功能），并且不应该真正对文档做出决定；这就是文档的用途。如果您有一个公开 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.