带有DoxyGen的Visual Studio用于文档,还是应该使用其他东西？

Question

我们目前正在使用DoxyGen来记录用C/C++,PHP和Java编写的代码.要拥有一致的环境,最好将它用于C#文档.

但是我们想知道:

• 您是否看到使用DoxyGen之外的其他内容生成的文档布局或结构有任何优势？我们正在为具有C#和.NET平台经验的外部开发人员生成文档.也许他们习惯了某种文档格式？
• DoxyGen与Visual Studio的集成程度如何？是否有能够从IDE内部一键式生成文档的东西？
• 是否有一些其他文档系统与Visual Studio更集成？

Answer 1

在Visual Studio中记录C#代码的默认方式是通过XML文档注释.在我看来,这是获得C#代码的最佳方式,因为对此的支持已集成在Visual Studio中(注释标记自动完成,警告有关缺失或拼写错误的参数,......).要记录方法,只需///在方法体前面键入三个斜杠(),Visual Studio将插入一个空的注释模板供您填充,如下所示:

/// <summary>
/// 
/// </summary>
/// <param name="bar"></param>
private void Foo(int bar)
{
    // ...
}

您可以将Visual Studio配置为从所有注释生成XML文件,然后将其输入到像Sandcastle这样的文档生成器中.如果你想使用Doxygen,这不是问题,因为它支持解析XML注释.

总结一下:我建议对C#代码使用特殊Doxygen注释的XML注释.这样你就有了所有的选择.您可以使用组织熟悉的标准Doxygen布局生成文档(因为Doxygen支持XML注释),还可以选择以.NET开发人员已知的格式生成文档(使用Sandcastle和Sandcastle帮助FileBuilder).

啊,还试试GhostDoc ......

Answer 2

文档有几种选择:

• 免费的Microsoft方式.使用DocXml文档注释,然后使用Sandcastle或类似工具构建MSDN样式的文档.这样做的好处是Visual Studio可以识别文档(它为注释添加语法颜色),并且Intellisense系统会立即获取文档(因此,如果将鼠标指针悬停在正在调用的方法上,工具提示将显示您在文档评论中输入的摘要和参数信息)

• 免费的Doxygen系统.这更容易使用且更灵活,但Visual Studio不支持,因此您失去了intellisense和语法着色的优点.从好的方面来说,Doxygen会解析DocXml格式,因此您可以通过使用带有Doxygen的DocXml格式来生成外部帮助,从而获得两全其美的效果.

• DocumentX等商业产品,允许您在WYSIWYG窗口中编辑文档.

我建议从DocXml注释和Doxygen开始生成外部帮助,因为这是最便宜和最简单的入门方式,并保留了VIsual Studio(intellisense等)的所有最佳功能.

我还建议你看一下我的插件Atomineer Pro Documentation,它可以在VS中更快更容易地生成和更新DocXml,Doxygen,Qt或JavaDoc格式的注释 - 是Doxygen和Sandcastle的理想补充.

Answer 3

Doxygen可以正常使用C#doc comments(///).正常记录您的代码并运行doxygen将它们扫描成独立的html,chm和pdf文件.这是迄今为止最通用,最简单和非侵入性的方法.

虽然doxygen没有集成到visual studio中,但它配备了一个简单的IDE,并且可以作为自定义外部工具轻松编写脚本.就个人而言,我已将doxygen集成到我的构建脚本中,并且它可以完美地运行.

最后,doxygen是跨平台的(如果您发现需要移植到Mono,这是一个优势)并且明显快于SandCastle(设置和运行).

这是~1Mloc项目中C#代码的doxygen输出示例:http://www.opentk.com/files/doc/annotated.html