VS.Net中VB注释及其帮助文档制作工具调查报告

 

[目的：]

1. 为了给通用底层dll文件制作帮助文件，便于项目组内交流，提高开发效率
2. 提高编码时注释的速度和规范性

[过程：]

1. 查找vb注释转帮助文件相关信息

通过在主要搜索引擎和CSDN社区上的查找发现GotDotNet社区上有一款开源插件(VBComment)可以像C#一样方便的进行块注释,主要用在NameSpace,Class,Function,Sub,Property等等，当编译程序时自动生成标准的可以制作帮助的XML文件

安装VBComment后运行VS.Net，从工具-外接程序管理器中添加VBComment Add-In，点击工具-VBComment Options可以设置块注释使用的前缀标记(‘ , ‘@ , ‘’’ 三种)

2. 接着又查找如何将注释过的程序生成帮助文档的信息

从VBComment的帮助文件中发现有两款软件可以为注释过的vb程序生成帮助文档，起初试用了第一个软件Custom Help Builder ，这也是一款开源软件，不知是由于该软件还不够成熟还是其他异常情况，试用过程中始终无法从VS.Net的工具中运行，这种情况也是该软件社区中反映比较多的情况，于是决定放弃。

后又从网上得知Document! X 4 这款软件，试用过程中发现这款软件功能强大易于使用，但美中不足，有60天试用时间限制，决定暂时放弃。

继续测试VBComment帮助文件中提及的后一种软件NDoc，这同样是款开源软件，起初下载了其1.2版本测试，新建WebControl项目，用VBComment插件添加注释，最后编译生成dll和xml文件。运行Ndoc解压包中bin目录下的net1.1中的NDocGui.exe，添加dll和xml文件，然后build，生成的帮助文档和预期效果有差别，后经过多次测试发现WebApplication 和 Class ，WebService等项目可以生成符合要求的帮助文档，而 webcontrol、wincontrol 和window、智能设备应用程序等类型的项目不行。后又测试了其1.3beta版，该版本增强了部分功能，增加了联机帮助和状态Output。另外Ndoc支持自定义Tag，使用方法，首先在注释中使用自定义Tag，也可以通过扩展VBComment来实现自动加入自定义Tag，然后再格式化自定义Tag输出的位置，创建包含以下代码的XSLT文件：
<?xml version="1.0" encoding="UTF-8" ?>

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

       <xsl:template match="mytag" mode="remarks-section">

              <h1 style="color:green">

                     <xsl:value-of select="."/>

              </h1>

       </xsl:template>

</xsl:stylesheet>

3. 根据公司开发规范及Alesh项目组开发的特点对VBComment扩展

程序开发时需要对所增加的功能模块进行注释，而之后根据要求会修改该模块。基于这样的情况扩展了VBComment的功能，修改程序时可以在注释的<history>块中自动添加修改标记（比如：添加、修改、删除）修改人和修改时间。使用方法：在<history>回车或在</history>行首回车。注释示例如下：
''' -----------------------------------------------------------------------------

        ''' <summary>

        ''' the web_test function

        ''' </summary>

        ''' <param name="ss"></param>

        ''' <returns></returns>

        ''' <remarks>

        ''' </remarks>

        ''' <history>

        '''        ===  chen.p   2004-7-18 14:33:17

        '''

        '''        ===  chen.p   2004-7-18 14:33:13

        ''' 上两行是从<history>后回车自动生成

        '''   [chen.p] 2004-7-15 Created

        ''' 上一行包括整块注释除===标记的是最初在Public Function 前输入'''回车后自动生成

        '''        ===  chen.p   2004-7-18 14:33:22

        '''        

        '''        ===  chen.p   2004-7-18 14:33:28

        ''' 上两行是在 ''' </history>行首回车后自动生成的

        ''' </history>

        ''' -----------------------------------------------------------------------------

        Public Function web_test(ByVal ss As String) As String

            Return ss & "88"

        End Function

4. 通过输入标志，加回车可以输入<history>tag
5. 通过配置Change Code，可以把缺陷编号和缺陷描述，快速输入到代码中。

 

[结论：]

通过安装扩展的VBComment插件结合Ndoc可以比较方便的将部分项目的注释转换成帮助文档以便日后方便的查找所需要的功能，理解程序模块，而不需要再一点一点地分析程序代码。另外还可以继续扩展VBComment按照公司的规范在文件头部加入文件注释。

[调查人：]

           Chen.P

           Liu.K.X

[调查时间：]

           2004-7-14 ~ 2004-7-15