6

我想将部分源代码添加到 XML 文档中。我可以将源代码复制并粘贴到一些 <code> 元素，如下所示：

/// <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 则......”。

另一种解决方案是将方法的主体复制并粘贴到注释字段中，然后将其放入 <code> 元素中。这个方法体可以很容易地理解，即使没有太多关于 C# 的知识——所以把它放在技术帮助文件中没有错。

这两种解决方案都违反了 DRY 原则！我想将方法​​体或方法体的片段添加到帮助文件中，而不重复信息。

这在 C# 中可能吗？（我认为 RDoc for Ruby 能够做到这一点，但我需要一些 C# 解决方案）

4

4 回答 4

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
}

我知道这并不漂亮，但这是一个开始！;)

于 2009-06-25T01:07:18.400 回答
1

为什么不使用更标准的方法来记录代码，方法是使用以下字段

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

只是一个想法。

于 2009-06-25T01:22:46.153 回答
1

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

如果这是第一次，我会使用代码。我会说，该方法计算费用时会考虑到不同的折扣规则以及算法中包含的其他内容。这些计算的业务规则在 API 上下文中不是重要信息，它们很可能会在不更改 API 的情况下发生更改（只有接口后面的实现会更改）

如果是第二个目的，重复代码仍然无法实现目的。重复某事确实使它更清晰，重复某事确实使它更清晰，但是如何使用该方法的示例可能有助于解释。使用示例不会重复，仅在方法签名更改时才需要更改，然后无论如何都需要更改文档

于 2009-06-25T06:36:30.120 回答
0

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

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

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

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

您将如何识别需要进入帮助文件的代码？在我的脑海中，我可以想到三个选项：

  • 属性
  • 地区
  • 评论

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

在结束语中，我想指出，虽然这当然是可能的，但它可能不仅仅是复制和粘贴并保持一点纪律:)

于 2009-06-25T07:15:28.827 回答