1

也许这有点像滑雪梦想/问题。有谁知道会生成 XML 或前缀表示法（lispy）的工具——其中包括来自 C# 源代码的文档注释？这似乎对许多文档生成器或静态分析工具或其他任何东西都有用。

不可否认，这是一种中间件工具，可能可以通过像 Antlr 这样的编译器生成器来完成。然而，有人可能已经抓痒并产生了一些类似的东西......嗯？

编辑：澄清：“包括来自 C# 源代码的文档注释”

我添加这个是为了区分 AST 可能不包含评论（尽管 Antlr 有一个可以流式传输评论的“频道”概念）。

编辑：至于要提取的内容：基本上是带有注释的 AST，但采用可重用的形式，即 Lispy 或 XML 就可以了。但它必须是完整的，以便如果一个重新用途不需要信息，另一个过程仍然可以从它的包含中受益。

希望有帮助。

L-

4

3 回答 3

2

那个痒是很久以前挠过的。

我们的源到源程序转换工具DMS Software Reengineering Toolkit可以针对多种语言执行此操作，包括使用 DMS 的C# Front End的 C# 。

请参阅下面的示例，其中 DMS 将源代码解析为 AST，并带有（前和后）注释装饰各种 AST 节点，然后以“Lispy”语法转储到输出流。还有一个简单的 XML 变体，只是为了满足那些必须拥有 XML 的人。

作为一般规则，DMS 用户只使用它来查看解析树，因为 DMS 提供了大量用于分析、转换和漂亮打印（从 AST 重新生成文本，包括注释）的机制。

使用 DMS 遍历 AST 并只挑选出满足您希望的任何标准的评论，包括“看起来像文档评论”，这将是非常简单的。更重要的是，您还可以获得精确的源位置信息，以及访问附加评论的树；您可以轻松地从方法头子树构建方法摘要。

大多数 DMS 用户想要做更复杂的事情，我们声称使用 DMS 提供的所有机制在 DMS 中做这件事比导出到 XML 或 Lisp 格式的一些临时工具要容易得多，在那里你必须重新发明所有这些又是机械。

对于此代码：

/* MyClass source file
   Contains MyClass and its methods
*/
class MyClass {

   static int count; // counts number of class instances

   MyClass() { count++; // bump instance count
     }

   /* First Method */
   get_count() { return count; }

}

DMS 的 C# 解析器生成此输出（注意嵌入的注释）：

Domain Parser for CSharp~CSharp4_0 2.3.3
Copyright (C) Semantic Designs 1996-2010; All Rights Reserved
Parsing Time: 0.001728 seconds
(compilation_unit@CSharp~CSharp4_0=1#58e66c0^0 Line 4 Column 1 File C:/temp/test.cs
 (extern_alias_directives@CSharp~CSharp4_0=2#58e3340 Line 4 Column 1 File C:/temp/test.cs)extern_alias_directives
 (using_directives@CSharp~CSharp4_0=493#58e3380 Line 4 Column 1 File C:/temp/test.cs)using_directives
 (global_attributes@CSharp~CSharp4_0=1008#58e33c0 Line 4 Column 1 File C:/temp/test.cs)global_attributes
 (namespace_member_declarations@CSharp~CSharp4_0=506#58e6440 Line 4 Column 1 File C:/temp/test.cs
  (namespace_member_declarations@CSharp~CSharp4_0=505#58e3400 Line 4 Column 1 File C:/temp/test.cs)namespace_member_declarations
  (namespace_member_declaration@CSharp~CSharp4_0=516#58e3dc0 Line 4 Column 1 File C:/temp/test.cs
   (class_declaration@CSharp~CSharp4_0=533#58e6280 Line 4 Column 1 File C:/temp/test.cs
   |(class_header@CSharp~CSharp4_0=526#58e3600 Line 4 Column 1 File C:/temp/test.cs
   | precomment 4:1 `/* MyClass source file

   Contains MyClass and its methods

*/'
   | (attributes@CSharp~CSharp4_0=1023#58e3440 Line 4 Column 1 File C:/temp/test.cs)attributes
   | (class_modifiers@CSharp~CSharp4_0=534#58e3480 Line 4 Column 1 File C:/temp/test.cs)class_modifiers
   | (optional_partial@CSharp~CSharp4_0=524#58e34c0 Line 4 Column 1 File C:/temp/test.cs)optional_partial
   | (identifier@CSharp~CSharp4_0=1106#58e3580 Line 4 Column 7 File C:/temp/test.cs
   |  (IDENTIFIER@CSharp~CSharp4_0=1171#58e3500[`MyClass'] Line 4 Column 7 File C:/temp/test.cs)IDENTIFIER
   | )identifier
   | (class_base@CSharp~CSharp4_0=552#58e35c0 Line 4 Column 15 File C:/temp/test.cs)class_base
   |)class_header
   |(class_member_declarations@CSharp~CSharp4_0=563#58e3c80 {3} Line 6 Column 4 File C:/temp/test.cs
   | (class_member_declaration@CSharp~CSharp4_0=573#58e3ce0 Line 6 Column 4 File C:/temp/test.cs
   |  (field_declaration@CSharp~CSharp4_0=591#58e3e00 Line 6 Column 4 File C:/temp/test.cs
   |   postcomment 5:1 `// counts number of class instances'
   |   (attributes@CSharp~CSharp4_0=1023#58e3300 Line 6 Column 4 File C:/temp/test.cs)attributes
   |   (field_modifiers@CSharp~CSharp4_0=593#58e3aa0 {1} Line 6 Column 4 File C:/temp/test.cs
   |   |(field_modifier@CSharp~CSharp4_0=607#58e3840 Line 6 Column 4 File C:/temp/test.cs)field_modifier
   |   )field_modifiers
   |   (integral_type@CSharp~CSharp4_0=42#58e3540 Line 6 Column 11 File C:/temp/test.cs)integral_type
   |   (variable_declarators@CSharp~CSharp4_0=104#58e3780 Line 6 Column 15 File C:/temp/test.cs
   |   |(variable_declarator@CSharp~CSharp4_0=112#58e38a0 Line 6 Column 15 File C:/temp/test.cs
   |   | (identifier@CSharp~CSharp4_0=1106#58e3d00 Line 6 Column 15 File C:/temp/test.cs
   |   |  (IDENTIFIER@CSharp~CSharp4_0=1171#58e3460[`count'] Line 6 Column 15 File C:/temp/test.cs)IDENTIFIER
   |   | )identifier
   |   |)variable_declarator
   |   )variable_declarators
   |  )field_declaration
   | )class_member_declaration
   | (class_member_declaration@CSharp~CSharp4_0=579#58e6580 Line 8 Column 4 File C:/temp/test.cs
   |  (constructor_declaration@CSharp~CSharp4_0=798#58e61a0 Line 8 Column 4 File C:/temp/test.cs
   |   (constructor_header@CSharp~CSharp4_0=792#58e6720 Line 8 Column 4 File C:/temp/test.cs
   |   |(attributes@CSharp~CSharp4_0=1023#58e38c0 Line 8 Column 4 File C:/temp/test.cs)attributes
   |   |(constructor_modifiers@CSharp~CSharp4_0=800#58e3b40 Line 8 Column 4 File C:/temp/test.cs)constructor_modifiers
   |   |(constructor_declarator@CSharp~CSharp4_0=815#58e3760 Line 8 Column 4 File C:/temp/test.cs
   |   | (identifier@CSharp~CSharp4_0=1106#58e3d40 Line 8 Column 4 File C:/temp/test.cs
   |   |  (IDENTIFIER@CSharp~CSharp4_0=1171#58e3d80[`MyClass'] Line 8 Column 4 File C:/temp/test.cs)IDENTIFIER
   |   | )identifier
   |   | (optional_formal_parameter_list@CSharp~CSharp4_0=647#58e6700 Line 8 Column 12 File C:/temp/test.cs)optional_formal_parameter_list
   |   | (constructor_initializer@CSharp~CSharp4_0=816#58e37c0 Line 8 Column 14 File C:/temp/test.cs)constructor_initializer
   |   |)constructor_declarator
   |   )constructor_header
   |   (block@CSharp~CSharp4_0=405#58e6780 Line 8 Column 14 File C:/temp/test.cs
   |   |(statement_list@CSharp~CSharp4_0=406#58e3d20 Line 8 Column 16 File C:/temp/test.cs
   |   | (non_pp_embedded_statement@CSharp~CSharp4_0=367#58e39a0 Line 8 Column 16 File C:/temp/test.cs
   |   |  postcomment 2:1 `// bump instance count'
   |   |  (statement_expression@CSharp~CSharp4_0=433#58e6540 Line 8 Column 16 File C:/temp/test.cs
   |   |   (primary_no_array_creation_expression@CSharp~CSharp4_0=160#58e6740 Line 8 Column 16 File C:/temp/test.cs
   |   |   |(identifier@CSharp~CSharp4_0=1106#58e3800 Line 8 Column 16 File C:/temp/test.cs
   |   |   | (IDENTIFIER@CSharp~CSharp4_0=1171#58e3700[`count'] Line 8 Column 16 File C:/temp/test.cs)IDENTIFIER
   |   |   |)identifier
   |   |   )primary_no_array_creation_expression
   |   |  )statement_expression
   |   | )non_pp_embedded_statement
   |   |)statement_list
   |   )block
   |  )constructor_declaration
   | )class_member_declaration
   | (class_member_declaration@CSharp~CSharp4_0=579#58e6220 Line 12 Column 4 File C:/temp/test.cs
   |  (constructor_declaration@CSharp~CSharp4_0=798#58e3a80 Line 12 Column 4 File C:/temp/test.cs
   |   (constructor_header@CSharp~CSharp4_0=792#58e6380 Line 12 Column 4 File C:/temp/test.cs
   |   |(attributes@CSharp~CSharp4_0=1023#58e3a00 Line 12 Column 4 File C:/temp/test.cs)attributes
   |   |(constructor_modifiers@CSharp~CSharp4_0=800#58e38e0 Line 12 Column 4 File C:/temp/test.cs)constructor_modifiers
   |   |(constructor_declarator@CSharp~CSharp4_0=815#58e36e0 Line 12 Column 4 File C:/temp/test.cs
   |   | (identifier@CSharp~CSharp4_0=1106#58e3a20 Line 12 Column 4 File C:/temp/test.cs
   |   |  (IDENTIFIER@CSharp~CSharp4_0=1171#58e6760[`get_count'] Line 12 Column 4 File C:/temp/test.cs
   |   |   precomment 0:1 `/* First Method */')IDENTIFIER
   |   | )identifier
   |   | (optional_formal_parameter_list@CSharp~CSharp4_0=647#58e6960 Line 12 Column 14 File C:/temp/test.cs)optional_formal_parameter_list
   |   | (constructor_initializer@CSharp~CSharp4_0=816#58e65a0 Line 12 Column 16 File C:/temp/test.cs)constructor_initializer
   |   |)constructor_declarator
   |   )constructor_header
   |   (block@CSharp~CSharp4_0=405#58e6200 Line 12 Column 16 File C:/temp/test.cs
   |   |(statement_list@CSharp~CSharp4_0=406#58e6160 Line 12 Column 18 File C:/temp/test.cs
   |   | (non_pp_embedded_statement@CSharp~CSharp4_0=373#58e3e60 Line 12 Column 18 File C:/temp/test.cs
   |   |  (null_coalescing_expression@CSharp~CSharp4_0=327#58e3e40 Line 12 Column 25 File C:/temp/test.cs
   |   |   (conditional_or_expression@CSharp~CSharp4_0=325#58e3ec0 Line 12 Column 25 File C:/temp/test.cs
   |   |   |(conditional_and_expression@CSharp~CSharp4_0=323#58e6a00 Line 12 Column 25 File C:/temp/test.cs
   |   |   | (inclusive_or_expression@CSharp~CSharp4_0=321#58e3c00 Line 12 Column 25 File C:/temp/test.cs
   |   |   |  (exclusive_or_expression@CSharp~CSharp4_0=319#58e3b20 Line 12 Column 25 File C:/temp/test.cs
   |   |   |   (and_expression@CSharp~CSharp4_0=317#58e35a0 Line 12 Column 25 File C:/temp/test.cs
   |   |   |   |(equality_expression@CSharp~CSharp4_0=314#58e6520 Line 12 Column 25 File C:/temp/test.cs
   |   |   |   | (additive_expression@CSharp~CSharp4_0=300#58e6140 Line 12 Column 25 File C:/temp/test.cs
   |   |   |   |  (multiplicative_expression@CSharp~CSharp4_0=296#58e6460 Line 12 Column 25 File C:/temp/test.cs
   |   |   |   |   (primary_no_array_creation_expression@CSharp~CSharp4_0=160#58e63a0 Line 12 Column 25 File C:/temp/test.cs
   |   |   |   |   |(identifier@CSharp~CSharp4_0=1106#58e37e0 Line 12 Column 25 File C:/temp/test.cs
   |   |   |   |   | (IDENTIFIER@CSharp~CSharp4_0=1171#58e6560[`count'] Line 12 Column 25 File C:/temp/test.cs)IDENTIFIER
   |   |   |   |   |)identifier
   |   |   |   |   )primary_no_array_creation_expression
   |   |   |   |  )multiplicative_expression
   |   |   |   | )additive_expression
   |   |   |   |)equality_expression
   |   |   |   )and_expression
   |   |   |  )exclusive_or_expression
   |   |   | )inclusive_or_expression
   |   |   |)conditional_and_expression
   |   |   )conditional_or_expression
   |   |  )null_coalescing_expression
   |   | )non_pp_embedded_statement
   |   |)statement_list
   |   )block
   |  )constructor_declaration
   | )class_member_declaration
   |)class_member_declarations
   |(optional_semicolon@CSharp~CSharp4_0=959#58e3b60 Line 16 Column 1 File C:/temp/test.cs)optional_semicolon
   )class_declaration
  )namespace_member_declaration
 )namespace_member_declarations
)compilation_unit
Exiting with final status 0
于 2011-10-06T21:09:35.070 回答
1

好的，现在更清楚您想要完整的 AST，MS 的标准工具中还没有任何内容。但是，C# 编译器团队目前正在开发“Roslyn”，也就是“编译器即服务”。预览版本很快就会到期 - 此时应该会更清楚这是否支持您所追求的。

目前尚不清楚 Roslyn 是否将作为 .NET 框架的一部分提供，或者它是否只会随 Visual Studio 的某些 SKU 一起提供 - 但它最终可能会比其他一些替代品更实惠。

原始答案

这已经是语言和普通工具的一部分 - 在 Visual Studio 中，只需转到项目属性/构建/输出并启用带有“XML 文档文件”的复选框。选择要写入文档的文件，然后离开。

从中构建可读的 HTML 有点棘手；Sandcastle会这样做，但需要一个帮助项目 - Sandcastle Help File Builder将其变成更易于管理的任务。不过，它的生成方式相当灵活 - 例如，您可以查看使用 Sandcastle 生成的 Noda Time 的 API 文档。

此外，如果您正在构建一个供其他人使用的类库，如果您将 XML 与 DLL 一起提供并且它具有相同的名称（只是使用 .xml 后缀而不是 .dll），Visual Studio 将使用它来为您提供用户使用您的类型、方法等时的工具提示。

于 2011-10-06T19:55:06.313 回答
0

我所知道的最接近的是Sandcastle。它使用 XML 作为中间输出并使用 XSLT 对其进行处理，以在托管程序集上创建 HTML 样式的文档。从中获取 XML 数据应该很容易。

于 2011-10-06T19:54:58.010 回答