用户自定义javadoc使用eclipse&Android studio

对于软件开发人员来说，查看API应该是基本的能力。但是我们自己怎么定义出我们自己的API？对于Android开发者而言，写代码是基本的，但是代码我们不只是写，还要理解，一份好的代码不是自己理解就OK的，最重要的是你写的代码后续维护的人要理解，(如果别人不理解，那就会在心里问候你全家啦，呵呵)所以能够让别人看懂你的代码是很重要的。因此我们就要学会给我们的代码加上注释，但是怎么让我们的注释随生成的javadoc一起生效呢，这里的生效是我们自定义的注释，系统的会自动生成的！下面就来详细讨论注释的使用。

注：本文章不介绍标记的使用。重点介绍如何生成javadoc和自定义标记。

javadoc 标记有如下一些：

标记	用于	作用
@author	对类的说明	标明开发该类模块的作者
@version	对类的说明	标明该类模块的版本
@see	对类、属性、方法的说明	参考转向，也就是相关主题
@param	对方法的说明	对方法中某参数的说明
@return	对方法的说明	对方法返回值的说明
@exception/throws	对方法的说明	对方法可能抛出的异常进行说明

一、使用Eclipse工具生成API和自定义javadoc。

例如下面的代码：

/**
* @author xlou
* @date 2017-12-8
* @version v1.0
*/
public interface IJavadocIntenerface {
/**
* @param  name
* @param  age
* @return boolean ture/false
* @throws NullPointerException 如果传入的参数为Null，则会抛出NullPointerException
*/
boolean generateJavaDoc(String name,int age) throws NullPointerException;
}

对于上面的代码是很简单的例子，现在我们需要将上面的代码生成javadoc，详细过程可以参考资料：jingyan.baidu.com/article/597a0643485c11312b5243c7.html。
详细过程如下：

1. 点击eclipse的【Project】菜单，选择【Generate JavaDoc】选项。

   
   
   

   image.png
2. 选择您要生成JavaDoc的工程
3. 选择哪些级别的内容生成JavaDoc，默认为public，如果选择private则会全部内容都生成。
4. 选择doc的生成位置，默认为工程目录下，建议不要修改。

5. 点击【Next】按钮

   
   
   

   image.png
6. 勾选Document Title，然后填写文档标题。

7. 点击【Next】按钮

   
   
   

   image.png
8. 选择使用的jdk版本

9. 点击【Finish】按钮

   
   
   

   image.png
   
   

   最后项目下生成一个【doc】的目录，里面存放着javadoc文档。

   
   
   

   image.png
   
   打开doc目录，用浏览器打开index.html。
   
   

   image.png
   
   
   对于以上的代码我们生成的DOC文档内容如下：
   

   jdoc.JPG
   
   到这里我们细心点可以发现，我们定义的@date没有生成，因为这是我们自己定义的，因此需要我们在生成Javadoc的时候进行配置。配置工作在以上第8、9步的时候，如下图配置：
   

   jdoc.JPG
   
   配置后生产的API文档如下：
   

   jdoc.JPG
   
   从上图可以看出我们自定义的@date就生成啦，如果要自定义多个怎么办呢？没关系，继续在后面追加内容就要可以，如：-tag version:a:"version:" -tag date:a:"date:"

• 如何使用Eclipse配置注释模板?

到这里我们详细介绍如何使用Eclipse配置注释模板，为什么要介绍模板呢？一句话：为了方便（哪里需要那么多理由啊，配置模板需要理由吗）。下面我们用类的注释来详解配置类的注释模板，函数的注释模板大同小异，这里就不一一介绍啦。

• 第一步，我们需要类注释模板的XML文件，我们定义了一个类的xml文件，xml文件名为Types.xml，内容如下：

怎么将这个xml文件做为类的注释模板导入eclipse呢？首先选择Eclipse工具栏Window下的Preference，进入如下框图，按图中1、2、3步骤选择：

jdoc.JPG

• 选择上图中的Import按钮，导入我们的Types.xml文件后就可以啦，最终成功后如下图：
  

  jdoc.JPG
  
  

  如上面红色框中就是我们自定义的模板，然后我们在类或者接口添加doc注释的时候就会自动生成如上模板的注释。

二、使用Android Studio生成API和自定义javadoc

现在我们详细介绍使用Android Studio来做上面的工作。利用Android Studio 生成API步骤如下：可以参考www.cnblogs.com/moneymanymany/p/5157317.html 。
首先介绍自定义注释模板以及快捷键：

1. 通过 File –>Settings 或者 HotKey Ctrl + Alt + S 打开 Settings面板，如下图
   

2. 点击 Editor下的Live Templates。如下图，显示的是Android Studio为开发者提供的默认模板及快捷键。
   

3. 为了自定义注释模板，点击右上角的“+”,选择Template Group创建一个自定义Template Group
   

4. 选择创建好的Template Group, 在点击“+”,选择Live Template创建一个自定义的Template
   

5. 选择创建好的Templat，如下图。在Abbreviation内输入字符串，例如decl。在Description内填写描述信息。
   

6. 在点击Template text输入框下方的Define，选择快捷键起作用的情况，选择Declaration，在函数前面输入decl后按回车即可以按模板生产注释
   

7. 在Template text内输入自定的注释模板，$xxx$这类的变量可以通过Edit variables来设置其含义
   

8. 如果要生成JavaDoc，就要按规则书写函数注释模板，规则可以参考 Editor –> Code Style –>Java –>JavaDoc
   

   最后生成javadoc。

9. 点击Tools –>Generate JavaDoc 来生成Java Doc
   

10. 界面选择如下：
    

    jdoc.JPG

11. 如果要自定义注释和设置编码格式，如下：
    

    jdoc.JPG
12. 如果生产Java Doc失败，检查 Include jdk and library sources in –sourcepath是否勾选。

Other command line arguments，设置Android SDK的bootclasspath和编码
1. -bootclasspath D:\AndroidSDK\sdk\platforms\android-23
2. -encoding utf-8
3. -charset utf-8

综上所述，是Eclipse和Android Studio的简便设置注释和生成javadoc的总结，有不对之处欢迎骚扰！！