这篇博客将要讨论的是关于:
如何从C#的source以及注释, 生成一份Word格式的关于各个类,函数以及成员变量的说明文档.
他的大背景如下......
最近的一个项目使用C#, 分N个模块,
在项目的里程碑的时候, 日本的总公司要检查我们的成果物.
成果物包括源代码, 概要设计式样书(SD,System Design), 详细设计式样书(PD, Program Design), 自动化测试等等.
源代码必须要符合编码规范(每个函数都要有注释, 方法变量的命名规则等...)
这些检查都很正常, 唯独一个比较辣手,那就是PD(一份Word文档).
PD中主要分两部分, 第一部分是UML图,
要求在UML图中,必须记载每一个变量名,函数名等等, 且必须与source完全一致.
这一点好办到, 只需要使用UML工具的逆向工程从source生成UML图即可.
PD中还需要的另一部分便是: 要为每一个类, 每一个变量, 每一个方法提供一个详细的说明(包括公有的和私有的一切)
以方法为例, 要求大概形如下面这样(类, 变量, 属性等类似):
这些关于方法,变量详细的记载, 同样要求与源代码一致(包括函数名, 参数, 函数注释等等)
在第一次做成这些文档和代码的时候还好些, 我们从一个地方拷贝到另一个地方, 他们初始是一致的,
然而接下来repeat的噩梦就开始了,两边同时维护, 总有漏下的,
而且需要花费很大的时间(尤其是检查),
有些时候, 日本方面的认真程度是我们中国人无法想象的,
比如从一份上百页的文档中, 他们能挑出某一个函数参数的大小写与source不一致这样的问题.
一个check不周,就有可能指摘.
关于问题, 已经介绍了差不多,
总之, 本着DRY原则,
同时也为了保证我们的这份word文档能够忠实于我们的source,
我想做的是: 从Source自动生成这份Word文档
为此要解决两个问题
1. 从Source中拿到相应的数据
2. 将相应的数据写到Word中.
对于第一个问题
,
visual studio中, [右键一个项目 -> property -> Build -> Output]处有一个叫做[XML documentation file]的选项,
勾上他之后, 在build的时候, 就会同时生成一个xml文件, 这个文件中包含各个类的方法,成员变量, 以及他们的xml注释.
关于这个问题, 还可以参考下面两个项目, 他们帮助我们生成MSDN Style的帮助文档.
Sandcastle - Documentation Compiler for Managed Class Libraries
Sandcastle Help File Builder
(我多么希望我们不需要维护这么一份word文件, 就使用上面的工具帮助我们生成MSDN Style的帮助文档就好....)
(然而总会有一些我们搞不定的人, 拥有一些和我们不同的喜好, 还好, 我们可以满足大家, 用程序生成这份文档吧....^-^)
对于第二个问题
,也就是如何用程序生成这份word文档,
在网上搜了一下, 使用word画表格的例子比较少(表格多的操作都用excel去了)
于是结合网上搜索的结果, 我写了下面的demo程序,
能够生成前面贴图效果的word文档(实际上, 前面的那个图, 就是对下面程序的输出做的一个截屏)
下面的代码只有一个函数,
在入口处设置一个断点, 边执行边看word文件的效果, 想了解word automation的,应该可以了解一个大概.
在调查的过程中, 我发现下面的三个连接提供的示例代码比较有用, 贴到下面供大家参考(第一篇讲解的尤为详细).
Word automation using C# @C#Corner
Word automation using C# @social.msdn.microsoft.com
HOW TO:利用 Visual C# .NET 使 Word 自动新建文
档 @MSDN
How to automate Microsoft Word to perform Mail Merge from Visual C# @MSDN
Automating Word Tables for Data Insertion and Extraction @MSDN
如果你使用的是其他语言, 但也需要维护一份这样的word文档的话,
大都可以使用类似的方法解决,
比如如果是java, javadoc同样可以帮助我们生成xml文档(而不仅仅局限于大家熟知的html), 然后我们从这个xml文档转换成我们需要的格式.
过程中要用到JELDoclet
, 详细做法参考这个链接Tip: Javadoc as XML @IBM DeveloperWorks
class WordAuto
{
Word.Application wApp;
Word._Document wDoc;
Object oMissing = System.Reflection.Missing.Value;
Object oFalse = false;
public void CreateFile()
{
Word.Selection wSelection;
Word.MailMerge wMailMerge;
Word.MailMergeFields wMergeFields;
Word.Table wTable;
int rowsNum = 12;
string StrToAdd;
// Create an instance of Word and make it visible.
wApp = new Word.Application();
wApp.Visible = true;
// Add a new document.
wDoc = wApp.Documents.Add(ref oMissing, ref oMissing, ref oMissing, ref oMissing);
wDoc.Select();
wSelection = wApp.Selection;
wSelection.ClearFormatting();
wSelection.Paragraphs.OutlineLevel = Word.WdOutlineLevel.wdOutlineLevel2;
wSelection.Font.Size = 20;
wSelection.Font.ColorIndex = Word.WdColorIndex.wdBlack;
wSelection.Font.Bold = 1;
wSelection.TypeText("my first method");
wApp.Selection.TypeParagraph();
wSelection.Paragraphs.OutlineLevel = Word.WdOutlineLevel.wdOutlineLevelBodyText;
wSelection.ClearFormatting();
wSelection.Font.ColorIndex = Word.WdColorIndex.wdBlack;
wSelection.TypeText("content of first......");
wTable = wDoc.Tables.Add(wSelection.Range, rowsNum, 4, ref oMissing, ref oMissing);
wTable.Rows[1].Cells.Shading.BackgroundPatternColorIndex = Word.WdColorIndex.wdGray25;
//wTable.Columns[1].SetWidth(51, Word.WdRulerStyle.wdAdjustNone);
wTable.Columns[1].SetWidth(70, Word.WdRulerStyle.wdAdjustProportional);
wTable.Columns[3].SetWidth(70, Word.WdRulerStyle.wdAdjustProportional);
wTable.Borders.Enable = 1;
wTable.Rows[1].Cells[1].Merge(wTable.Rows[1].Cells[4]);
wTable.Rows[1].Cells[1].Range.InsertAfter("MyNameSpace.MyClass#MyMethod() : MyRetureType");
for (int i = 6; i <= rowsNum; i++)
{
wTable.Rows[i].Cells[2].Merge(wTable.Rows[i].Cells[4]);
}
wTable.Rows[6].Cells[1].Range.InsertAfter("详细定义");
wTable.Rows[7].Cells[1].Range.InsertAfter("事前条件");
wTable.Rows[8].Cells[1].Range.InsertAfter("事后条件");
wTable.Rows[9].Cells[1].Range.InsertAfter("不变制约");
wTable.Rows[10].Cells[1].Range.InsertAfter("非机能制约");
wTable.Rows[11].Cells[1].Range.InsertAfter("备考");
wTable.Rows[12].Cells[1].Range.InsertAfter("异常");
wTable.Rows[2].Cells[1].Range.InsertAfter("函数输入");
wTable.Rows[2].Cells[2].Range.InsertAfter("key::string");
wTable.Rows[2].Cells[3].Range.InsertAfter("概要");
wTable.Rows[2].Cells[4].Range.InsertAfter("my key to....");
wTable.Rows[3].Cells[3].Range.InsertAfter("制约");
wTable.Rows[3].Cells[4].Range.InsertAfter("key != null");
wTable.Rows[4].Cells[1].Range.InsertAfter("函数输出");
wTable.Rows[4].Cells[2].Range.InsertAfter("-");
wTable.Rows[4].Cells[3].Range.InsertAfter("概要");
wTable.Rows[5].Cells[3].Range.InsertAfter("制约");
Cell startCell1 = wTable.Rows[2].Cells[1];
Cell endCell1 = wTable.Rows[3].Cells[1];
Cell startCell2 = wTable.Rows[2].Cells[2];
Cell endCell2 = wTable.Rows[3].Cells[2];
Cell startCell3 = wTable.Rows[4].Cells[1];
Cell endCell3 = wTable.Rows[5].Cells[1];
Cell startCell4 = wTable.Rows[4].Cells[2];
Cell endCell4 = wTable.Rows[5].Cells[2];
startCell1.Merge(endCell1);
startCell2.Merge(endCell2);
startCell3.Merge(endCell3);
startCell4.Merge(endCell4);
// Go to the end of the document.
Object oConst1 = Word.WdGoToItem.wdGoToLine;
Object oConst2 = Word.WdGoToDirection.wdGoToLast;
wApp.Selection.GoTo(ref oConst1, ref oConst2, ref oMissing, ref oMissing);
wSelection.InsertBreak();
wSelection.Paragraphs.OutlineLevel = Word.WdOutlineLevel.wdOutlineLevel2;
wSelection.Font.ColorIndex = Word.WdColorIndex.wdBlack;
wSelection.Font.Size = 20;
wSelection.Font.Bold = 1;
wSelection.TypeText("my second method");
wApp.Selection.TypeParagraph();
wSelection.Paragraphs.OutlineLevel = Word.WdOutlineLevel.wdOutlineLevelBodyText;
wSelection.ClearFormatting();
wSelection.Font.ColorIndex = Word.WdColorIndex.wdBlack;
wSelection.TypeText("content of second......");
//another table
wTable = wDoc.Tables.Add(wSelection.Range, rowsNum, 4, ref oMissing, ref oMissing);
wTable.Borders.Enable = 1;
////............
wDoc.SaveAs("c:\\word_auto.doc");
wDoc.Close(false);
wApp.Quit();
wApp = null;
}
}
---end---
分享到:
相关推荐
选择“Add Documentation Source”,然后在弹出的对话框中选择你之前生成XML注释的C#项目,例如"BookLib"。 3. 设置项目属性。在SHFB的项目属性中,你可以指定文档的格式(如HtmlHelp1)、目标.NET Framework版本...
- 方法或函数应包含XML文档注释,方便自动生成API文档。 #### 六、空白与缩进规范 **6.1 术语** - 空白包括空格、制表符等。 **6.2 缩进对齐的要求** - 代码块内的语句应统一使用4个空格进行缩进。 **6.3 换行...
### C#编程代码规范 #### 一、大小写约定 **1、大小写方式** - **Pascal 大小写** - 在这种大小写方式中,标识符的第一个字母以及之后连接的每个单词的第一个字母都会被大写。这种方式通常用于类、接口、枚举...
- DOM(Document Object Model):将整个XML文档加载到内存中形成一棵树形结构,便于遍历和操作,但消耗资源。 - SAX(Simple API for XML):事件驱动模型,只处理文档的一部分,按需读取,节省内存,适合大型...
10. **最佳实践和编码规范**:书中的源代码将展示良好的XML编码习惯,包括文档编码、命名约定、注释和格式化,这些都是编写可维护和可读性高的XML文档的基础。 通过阅读和研究"XML入门经典"的源代码,你将能深入...
- 使用XML文档注释; - 避免过度注释。 - **实践建议:** 有效的注释可以极大地提高代码的可读性和可维护性,但应避免对显而易见的代码进行冗余注释。 #### 二、变量与常量 **7. 变量命名:** - **规范要点:*...
SourceInsight的配置文件是`.xml`格式,通常命名为`SourceInsight 4.x.x.xml`,其中`x.x`代表版本号。这个文件包含了用户的工作环境设置,如颜色主题、字体大小、快捷键绑定、项目设置等。通过导入和导出配置文件,...
在类或方法上右键点击选择“属性” -> “生成” -> “XML 文件”,可以生成包含类或方法文档注释的 XML 文件。这对于团队协作和后期维护非常有用,因为它可以帮助其他开发者更好地理解代码的功能和用途。 #### 八、...
开发者可能使用XML注释或其他工具生成API文档,以便于理解和维护。 总的来说,这个银行管理系统项目利用了C#的强大功能和灵活性,结合数据库技术、安全性措施和良好的编程实践,构建了一个高效、安全的业务处理平台...
- **XML文档注释**:为公开的方法、属性、事件等添加XML文档注释,以便自动生成API文档,提高代码的可读性和可用性。 - **缩进**:使用四个空格进行缩进,避免使用制表符,以保持一致性和美观性。 - **行长度**:每...
C#的XML注释是一种特殊形式的代码注释,它允许开发者在代码中添加结构化的文档,这些文档在编译时可以被转换成XML格式,方便生成API文档或其他技术文档。这种注释方式增强了代码的可读性和文档的生成效率。 在C#中...
源码中的注释和文档对于理解Ribbon控件的工作原理及其与其他组件的交互方式非常有帮助。此外,它还可以作为一个模板,为开发者提供自定义Ribbon界面的起点,从而快速实现自己的界面设计方案。 "SourceCode"这个文件...
1. **DOM解析(DOM解析器)**:Document Object Model,将整个XML文件加载到内存中形成一个树形结构,允许开发者遍历和修改整个文档。优点是操作灵活,缺点是占用内存大,不适合大型XML文件。 2. **SAX解析(SAX解析器)...
描述中的"C write a DLL source code control"暗示我们将探讨如何使用C#编写和管理DLL源代码。创建DLL涉及以下几个关键步骤: 1. **定义接口**:在C#中,我们可以使用接口(Interface)来定义DLL对外暴露的方法。...
在Windows Presentation Foundation (WPF) 中,开发人员经常需要集成PDF文件查看功能,以便用户能够直接在应用程序中浏览PDF文档。本文将深入探讨如何在WPF应用中实现PDF文件的浏览,包括各种技术和最佳实践。 首先...
XML文档型注释 357 第14章 用ADO.NET访问数据 360 关系型数据库与SQL 360 ADO.NET对象模型 364 开始使用ADO.NET 366 使用OLE DB托管提供程序 369 使用数据绑定控件 371 第15章 ASP.NET程序与Web Services编程 380 ...
XML文档型注释 357 第14章 用ADO.NET访问数据 360 关系型数据库与SQL 360 ADO.NET对象模型 364 开始使用ADO.NET 366 使用OLE DB托管提供程序 369 使用数据绑定控件 371 第15章 ASP.NET程序与Web Services编程 380 ...