C# 如何使源代码成为XML文档的一部分而不违反DRY?
我想将部分源代码添加到XML文档中。我可以将源代码复制粘贴到一些C# 如何使源代码成为XML文档的一部分而不违反DRY?,c#,.net,dry,documentation-generation,C#,.net,Dry,Documentation Generation,我想将部分源代码添加到XML文档中。我可以将源代码复制粘贴到一些元素上,如下所示: /// <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.Re
元素上,如下所示:
/// <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();
}
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;
}
}
保持这一点将是痛苦的。是否有其他可能将源代码添加到C#中的XML文档中
我正在使用Sandcastle处理XML文档,并希望从中生成一个技术帮助文件(*.chm)。我想将部分或完整的方法体添加到该帮助文件中
编辑:
谢谢您对slide_rule的评论。我添加了一个更现实、不那么琐碎的示例:
假设我有这样的方法:
/// <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();
}
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;
}
}
public decimal CalculateFee(账单)
{
如果(账单总额<5000)返回500;
其他的
{
if(bill.containssspecialoffer)返回bill.TotalSum*0.01;
否则返回bill.TotalSum*0.02;
}
}
如果能够在技术帮助文件中添加如何计算费用的信息,那就太好了
最明显的解决办法是将算法以平淡无奇的文字写在评论中,比如:“如果账单总额少于5000,那么……”
另一种解决方案是将方法体复制粘贴到comment字段中,并将其放入元素中。这个方法体很容易理解,甚至不需要太多关于C#的知识——所以把它放到技术帮助文件中并没有错
这两种解决方案都违反了干燥原则我想在帮助文件中添加方法体或方法体的片段,而不复制信息
这在C#中可能吗?(我认为RDoc for Ruby能够做到这一点,但我需要一些C#中的解决方案)只是提出了一个想法
自动执行查找以某种方式分隔的代码块的过程,然后将该代码注入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
}
我知道这不漂亮,但这是一个开始!;) 为什么不采用一种更标准的方法,通过使用类似
<summary>
<description>Displays Hello World!</description>
<arguments>None</arguments>
<returns>None</returns>
</summary>
显示你好世界!
没有一个
没有一个
只是一个想法。对我来说,注释的主要目的是描述代码。复制和粘贴代码并不能满足这个目的,所以我想我的问题应该是“文档的预期目的是什么?”您是否希望记录该方法对调用方法+(类似于API文档)的人所做的操作或者,您是否需要记录该方法如何工作,以便其他开发人员能够维护源代码?还是别的什么
如果这是第一次,我会使用代码。我想说明的是,该方法计算费用时考虑了不同的折扣规则以及算法中包含的内容。这些计算的业务规则在API上下文中不是重要的信息,它们很可能会在不改变API的情况下发生变化(只有接口后面的实现会发生变化)
如果这是第二个目的,重复代码仍然无法达到目的。重复某件事确实会让它更清晰,重复某件事确实会让它更清晰,但是一个如何使用该方法的示例可能有助于解释。使用示例不会重复,仅当方法签名发生更改时才需要更改,然后无论如何都需要更改文档中的内容您可能希望使用。我从未使用过它,所以我不知道是否可以将该元素与其他常规XML注释元素混合使用,但我阅读(稀疏)文档的方式与之不同
虽然这是最好的选择,但即使不可能,您也可以将该元素的使用与找到相关代码片段并将其插入XML文件的脚本结合起来
不过,我可能会走另一条路。因为XML注释的输出只是一个XML文件,所以您可以在创建XML注释后,但在对其运行Sandcastle之前对其进行处理。然后,我将创建另一个脚本,查找需要进入帮助文件的所有代码,并将其提取到单独的XML文件中
然后可以使用XSLT合并这两个XML文件并将其传递给SandCastle
如何识别需要进入帮助文件的代码?在我脑海中,我可以想到三个选择:
- 属性
- 地区
- 评论
就个人而言,我更喜欢属性
在结束语中,我想指出,虽然这当然是可能的,但这可能比复制和粘贴以及保持一点纪律性要复杂得多:)在我看来,您正在与XML文档的目的作斗争——如果我理解正确的话,XML文档更多地是关于API文档,而不是应用程序或技术文档。你能提供一个不那么琐碎的例子来说明你在做什么吗?谢谢你的提示。。。这就是没人回答的原因我将使用单元测试用例“记录”技术帮助文件。由于开发人员将是阅读它的人,单元测试将提供在代码中定义事物的最佳、最确定的方式。@Adrian Godong:类似的事情经常发生在我身上:Problem domain guy:“嘿,我们现在怎么计算费用?我手头没有需求文件。你能看看源代码吗?“我:”呃。。。“确定”打开帮助文件并向他显示帮助文件“我:”如果您需要,可以从SVN中查看帮助文件,并且您是最新的。这个帮助文件没有源代码那么可怕。试试看。”@RunningMonkey-我担心这段对话的潜台词是:PDG:“嘿,我们现在怎么计算费用?我觉得你的时间比我的少,我忘了文件在哪里,也懒得去找。你能帮我把它们挖出来吗?——告诉他们在帮助文件(甚至是sourc)中查找的位置