Question

我想将部分源代码添加到XML文档中。我可以复制＆amp;将源代码粘贴到某些＆lt; code＆gt;元素，像这样：

/// <summary>
/// Says hello world in a very basic way:
/// <code>
///   System.Console.WriteLine("Hello World!");
///   System.Console.WriteLine("Press any key to exit.");
///   System.Console.ReadKey();
/// </code>
/// </summary>
static void Main() 
{
    System.Console.WriteLine("Hello World!");
    System.Console.WriteLine("Press any key to exit.");
    System.Console.ReadKey();
}

维持这一点将是痛苦的。是否有其他可能性将源代码添加到C＃中的XML文档中？

我正在使用Sandcastle处理XML文档，并希望从中提供技术帮助文件（* .chm）。我想在该帮助文件中添加部件或完整的方法体。

修改感谢slide_rule的评论。我添加了一个更现实，更简单的例子：

假设我有这样的方法：

public decimal CalculateFee(Bill bill)
{
    if (bill.TotalSum < 5000) return 500;
    else
    {
        if (bill.ContainsSpecialOffer) return bill.TotalSum * 0.01;
        else return bill.TotalSum * 0.02;
    }
}

如果有可能将费用计算方法添加到技术帮助文件中，那将是很好的。

最明显的解决方案是将算法写成平淡无奇的文本到评论中：“如果账单的总金额少于5000，则......”。

另一个解决方案是复制＆amp;将方法的主体粘贴到注释字段中，并将其放入＆lt; code＆gt;元件。即使没有太多关于C＃的知识，也可以很容易地理解这个方法体 - 所以将它放入技术帮助文件中没有任何错误。

这两个解决方案都违反了DRY原则！我想将方法主体或方法主体的各个部分添加到帮助文件中，而不会重复信息。

这在C＃中是否可行？（我认为RDoc for Ruby能够做到这一点，但我需要在C＃中使用一些解决方案）

Answer 1

只是在那里抛出一个想法......

自动执行查找以某种方式分隔的代码块的过程，然后将该代码注入XML注释。

/// <summary>
/// Says hello world in a very basic way:
/// <code>
///     Code block 1
/// </code>
/// </summary>
static void Main() 
{
    // Code block 1 start
    System.Console.WriteLine("Hello World!");
    System.Console.WriteLine("Press any key to exit.");
    System.Console.ReadKey();
    // Code block 1 end
}

我知道它不漂亮，但它是一个开始！ ;）

Answer 2

为什么不使用更标准的方法来使用

等字段来记录代码

<summary>
   <description>Displays Hello World!</description>
   <arguments>None</arguments>
   <returns>None</returns>
</summary>

只是一个想法。

Answer 3

对我来说，评论的主要目的是描述代码。复制和粘贴代码不会满足于此目的，所以我想我的问题应该是“文档的预期目的是什么？”您是否希望记录该方法对调用方法+（有点像API文档）的方法所做的操作，或者您要记录该方法的工作原理以便其他开发人员可以维护源代码？还是别的什么？

如果是第一个我会使用代码的话。我会说该方法计算费用，考虑到折扣的不同规则，并且算法中包含了whatelse。这些计算的业务规则在API上下文中并不是一个重要的信息，它们很可能随着API的变化而变化（只有接口背后的实现会发生变化）

如果是第二个目的，那么重复代码仍然无法满足目的。重复一些事情确实使它更清楚，重复一些事情确实使它更清楚，但是如何使用该方法的一个例子可能有助于解释。用法示例不会重复，只需要在方法签名发生变化时进行更改，然后无论如何都需要更改文档

Answer 4

您可能想要使用include element。我从来没有使用它，所以我不知道你是否可以将该元素与其他常规的XML Comment元素混合在一起，但是我阅读（稀疏）文档的方式看起来并不像它。

虽然这是最好的选择，即使这是不可能的，但您可以将该元素的使用与查找相关代码片段并将其插入XML文件的脚本结合使用。

但是，我可能会采取另一种方式。由于XML Comments的输出只是一个XML文件，因此您可以在创建它之后但在运行Sandcastle之前对其进行处理。然后我会创建另一个脚本来查找需要进入帮助文件的所有代码，并将其解压缩到单独的XML文件中。

然后可以使用XSLT合并这两个XML文件并传递给SandCastle。

您如何识别需要进入帮助文件的代码？我能想到三个选择：

属性
地区
评论

就个人而言，我更喜欢属性。

在结束语中我想指出，虽然这当然是可能的，但它可能比复制和粘贴以及保持一些纪律更多的工作：）

如何使源代码成为XML文档的一部分而不是违反DRY？

4 个答案: