文档注释的配置与各个IDE生成文档

文档注释的配置与各个IDE生成文档

前言

编程这么多年（也就两年吧），没有深刻认识到文档注释的牛逼，今天来学习一下

 

 

 

 

 

---

IDEA与Java文档

文档注释

我们以IDEA编写java程序来示范，主要参考文章是这里：

类注释模板

在IDEA的Setting=》File and Code Template中的File=》Class设置类注释，例如我的内容如下：

/**
 * @ClassName ${NAME}
 * @Description TODO
 * @Author ${USER}
 * @Date ${DATE} ${TIME}
 * @Version 1.0
 */

Class文件

（1）${NAME}：设置类名，与下面的${NAME}一样才能获取到创建的类名

（2）TODO：代办事项的标记，一般生成类或方法都需要添加描述

（3）${USER}、${DATE}、${TIME}：设置创建类的用户、创建的日期和时间，这些事IDEA内置的方法，还有一些其他的方法在绿色框标注的位置，比如你想添加项目名则可以使用${PROJECT_NAME}

（4）1.0：设置版本号，一般新创建的类都是1.0版本，这里写死就可以了

 

方法注释模板

IDEA还没有智能到自动为我们创建方法注释，这就是要我们手动为方法添加注释，使用Eclipse时我们生成注释的习惯是

/**+Enter，这里我们也按照这种习惯来设置IDEA的方法注释。

打开：File–>Settings–>Editor–>Live Templates。

新建一个组，叫做userDefine

新建模板：命名为*

因为IDEA生成注释的默认方式是：/*+模板名+快捷键（比如若设置模板名为add快捷键用Tab，则生成方式为

/*add+Tab），如果不采用这样的生成方式IDEA中没有内容的方法将不可用，例如获取方法参数的methodParameters(）、

获取方法返回值的methodReturnType(）

然后下面的模板文本写上如下内容（要去掉最前面的/*）：

*
 * @Author $user$
 * @Description //TODO 
 * @Date $time$ $date$
 * @Param $param$
 * @return $return$
 **/

点击模板页面最下方的警告，来设置将模板应用于那些场景，一般选择EveryWhere–>Java即可

（如果曾经修改过，则显示为change而不是define）

最后，我们选择右侧的Edit variables按钮，来设置获取参数的方式。

大功告成，我们可以使用/**+Enter来测试。

 

生成文档

IDEA=》工具=》生成JavaDoc

 

 

这里的生成有一个坑，javadoc命令运行时，默认用了gbk，需要我们在＂Tools->Gerenate JavaDoc”面版的Other command line arguments 栏里输入：-encoding utf-8 -charset utf-8

 

 

 

---

VS Studio 与 C#文档

直接在vs中编写C#的时候加入注释文档（通过文档注释“///”），内容：

    class Program
    {
        /// <summary>
        /// 姓名
        /// </summary>
        public string Name { get; set; }
        /// <summary>
        /// 年龄
        /// </summary>
        public int Age { get; set; }
        /// <summary>
        /// 自我介绍
        /// </summary>
        /// <param name="name">姓名</param>
        /// <param name="age">年龄</param>
        /// <returns>自我介绍的内容</returns>
        public string Say(string name, string age)
        {
            return "My name is" + name + ",Age:" + age;
        }

        static void Main(string[] args)
        {
            Program p = new Program();
            Console.WriteLine(p.Say("李如一", "34"));
        }
    }

然后我们点开该项目的属性，然后选择生成，最下面的输出中，勾选生成xml文档文件，然后Ctrl+S保存，然后编译项目即可。

最后生成的xml文件：

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>测试注释文档的项目</name>
    </assembly>
    <members>
        <member name="P:测试注释文档的项目.Program.Name">
            <summary>
            姓名
            </summary>
        </member>
        <member name="P:测试注释文档的项目.Program.Age">
            <summary>
            年龄
            </summary>
        </member>
        <member name="M:测试注释文档的项目.Program.Say(System.String,System.String)">
            <summary>
            自我介绍
            </summary>
            <param name="name">姓名</param>
            <param name="age">年龄</param>
            <returns>自我介绍的内容</returns>
        </member>
    </members>
</doc>

关于文档注释中各个键值的意义：

文档生成器必须接受和处理任何根据 XML 规则有效的标记。下列标记提供了用户文档中常用的功能。（当然，也可能有其他标记。）

标记	章节	用途
<c>	A.2.1	将文本设置为类似代码的字体
<code>	A.2.2	将一行或多行源代码或程序输出设置为某种字体
<example>	A.2.3	表示所含的是示例
<exception>	A.2.4	标识方法可能引发的异常
<include>	A.2.5	包括来自外部文件的 XML
<list>	A.2.6	创建列表或表
<para>	A.2.7	用于将结构添加到文本中
<param>	A.2.8	描述方法或构造函数的参数
<paramref>	A.2.9	确认某个单词是参数名
<permission>	A.2.10	描述成员的安全性和访问权限
<summary>	A.2.11	描述一种类型
<returns>	A.2.12	描述方法的返回值
<see>	A.2.13	指定链接
<seealso>	A.2.14	生成“请参见”项
<summary>	A.2.15	描述类型的成员
<value>	A.2.16	描述属性

 

 

---

 

 

 

商业转载 请联系作者获得授权，非商业转载 请标明出处，谢谢