C# 到 XML 或前缀表示法
也许这就是一个不切实际的梦想/问题。有谁知道有一个工具可以生成 XML 或前缀表示法 (lispy)——其中包括来自 C# 源代码的文档注释？这似乎对许多文档生成器、静态分析工具或其他工具很有用。
诚然，这是一种中间件工具，可能可以通过像 Antlr 这样的编译器生成器来完成。然而，有人可能已经抓到了痒痒并产生了类似的东西......嗯？
编辑：澄清： “其中包括来自 C# 源代码的文档注释”
我添加此内容是为了区分 AST 可能不会包含注释（尽管 Antlr 有一个可以流式传输注释的“通道”概念）。
编辑：至于要提取的内容： 基本上是带有注释的 AST，但是采用可重用的形式，即 Lispy 或 XML 就可以了。但它必须是完整的，这样如果一个重新用途不需要信息，另一个流程仍然可以从它的包含中受益。
希望有帮助。
L-
Maybe this is kind of a pie-in-the-ski dream/question. Does anyone know of a tool that will produce XML or prefix-notation (lispy) -- that includes documentation comments from C# source code? It seems like this would be useful to a number of documentation generators, or static analysis tools, or whatever.
Admittedly this is a middle-ware kind of tool, and probably could be done via a compiler-generator like Antlr. However, someone might have scratched an itch and produced something along these lines... eh?
Edit: To Clarify:
"that includes documentation comments from C# source code"
I add this to distinguish that an AST probably won't include comments (though Antlr has a 'channel' concept that can stream comments).
Edit: As far what to extract:
Well basically the AST, with Comments, but in a form that is reusable, ie Lispy or XML would be fine. But it would have to be complete so that if one re-purpose doesn't need information another process could still benefit from its inclusion.
Hope that helps.
L-
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（3）
那种痒感早就被抓破了。
我们的源到源程序转换工具，DMS 软件重新工程工具包可以做到这适用于许多语言，包括使用 DMS 的 C# 前端。
请参阅下面的示例，其中 DMS 将源代码解析为 AST，并使用（前和后）注释装饰各个 AST 节点，然后以“Lispy”语法转储到输出流。还有一个简单的 XML 变体，只是为了满足那些必须使用 XML 的人。
作为一般规则，DMS 用户仅使用它来查看解析树，因为 DMS 提供了大量用于分析、转换和漂亮打印（从 AST 重新生成文本，包括注释）的机制。
使用 DMS 遍历 AST 并仅挑选那些满足您希望的任何标准的注释（包括“看起来像文档注释”）是非常简单的。更重要的是，您还可以获得精确的源位置信息，以及访问评论所附加的树；您可以轻松地从方法头子树构建方法的摘要。
大多数 DMS 用户想要做更复杂的事情，我们声称使用 DMS 提供的所有机制在 DMS 中更容易做到这一点，而不是导出到 XML 或 Lisp 格式的一些临时工具，在这些工具中您必须重新发明所有这些又是机械。
对于此代码：
DMS 的 C# 解析器生成此输出（注意嵌入的注释）：
That itch was scratched long ago.
Our source-to-source program transformation tool, the DMS Software Reengineering Toolkit can do this for many languages, including C# using DMS's C# Front End.
See the example below, in which source code is parsed by DMS into an AST with (pre- and post-) comments decorating the various AST nodes, and then dumped to an output stream in "Lispy" syntax. There's a trivial XML variant, too, just to satisfy those folks that must have XML.
As a general rule, DMS users only use this to look at parse trees , because DMS provides a vast amount of machinery for analyzing, transforming and prettyprinting (regenerating text, including comments, from the AST).
It would be pretty trivial to use DMS to walk the AST and pick out only those comments which satisfied whatever criteria you wished, including "looks like a documentation comment". More importantly, you also get precise source location information, as well as access to the tree to which the comment is attached; you could easily build summaries of the methods from the method header subtree.
Most DMS users want to do more complicated things, which we claim is much easier to do in DMS using the all the machinery DMS provides, than exporting to some ad hoc tool in XML or Lisp format, where you have to re-invent all that machinery again.
For this code:
DMS's C# parser produces this output (note embedded comments):
好的，现在很清楚您想要一个完整的 AST，MS 的标准工具中还没有任何内容。。然而，C# 编译器团队目前正在开发“Roslyn”，又名“编译器即服务”。预览版本很快就会到期 - 届时应该会更清楚这是否支持您所追求的内容。
目前尚不清楚 Roslyn 是否将仅作为 .NET 框架的一部分提供，或者是否仅随 Visual Studio 的某些 SKU 一起提供 - 但它最终可能比其他一些替代方案更便宜。
原始答案
这已经是语言和普通工具的一部分 - 在 Visual Studio 中，只需转到项目属性/构建/输出并启用“XML 文档文件”复选框。选择要写入文档的文件，然后就可以开始了。
从中构建可读的 HTML 有点棘手； Sandcastle 可以做到这一点，但需要一个帮助项目 - Sandcastle 帮助文件生成器 将其变成更易于管理的任务。不过，它生成的内容相当灵活 - 例如，您可以查看 使用 Sandcastle 生成的 Noda Time API 文档。
此外，如果您正在构建供其他人使用的类库，如果您将 XML 与 DLL 一起提供并且它具有相同的名称（只是使用 .xml 后缀而不是 .dll），Visual Studio 将使用它来为您提供用户使用您的类型、方法等时的工具提示。
Okay, now it's clearer that you want a full AST, there's nothing in the standard tools from MS yet. However, the C# compiler team are currently working on "Roslyn" aka "compiler as a service". Preview builds are due very soon - at which point it should become clearer whether or not this supports what you're after.
It's unknown at the moment whether Roslyn will be available just as part of the .NET framework or whether it'll only ship with some SKUs of Visual Studio - but it may well end up being more affordable than some other alternatives.
Original answer
This is already part of the language and normal tools - in Visual Studio, just go to Project Properties / Build / Output and enable the checkbox with "XML Documentation File". Pick the file to write the docs to, and away you go.
Building readable HTML from that is slightly trickier; Sandcastle will do this, but needs a helper project - Sandcastle Help File Builder to turn it into a more manageable task. It's fairly flexible in what it produces though - for an example, you could look at the API documentation for Noda Time which is generated with Sandcastle.
Additionally, if you're building a class library for others to use, if you ship the XML alongside the DLL and it has the same name (just with a .xml suffix instead of .dll), Visual Studio will use it to give your users tooltips when they use your types, methods etc.
我所知道的最接近的是Sandcastle。它使用 XML 作为中间输出，并使用 XSLT 对其进行处理，以通过托管程序集创建 HTML 样式的文档。从中获取 XML 数据应该很容易。
The closest thing I know of is Sandcastle. It uses XML as intermediate output and processes it with XSLT to create HTML-style documentation over managed assemblies. It should be quite easy to get just the XML data out of it.