文档注释的配置与各个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 描述属性

 

 


 

 

 

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

 

发表评论