Java学习4--包机制，JavaDoc

包机制，JavaDoc

• 包package的概念

包机制package,一个代码 如果有package定义，一般会放在最上面，不然会报错

类似于将文件归纳分类放置，包语句的语法格式为:
package pkg1[.pkg2[.pkg3…]];

工业上，一般公司会用域名的倒置作为包名，比如com.baidu.www
为了能够使用某一个包的成员，我们需要在java程序中明确导入该包，使用import语句可完成此功能
import package1.[.package2…].(classname|*);

• 包的调用

比如调用了Date，那么就需要在程序的顶端补充上java系统包的路径，比如
import java.util.Date;
这样可以将java系统自带的包给调用出来

但是无论如何，package即这个文件在整个电脑里的路径，需要写在文件的最最顶端。

JavaDoc

注：API–Application Programming Interface程序之间的接口
JavaDoc命令是用来快速生成该程序API文档的(Java API 文档速成器)
通过 Javadoc 生成 API 帮助文档，Java 帮助文档主要用来说明类、接口、方法、成员变量、构造器和内部类–帮助别人使用这个程序。

JavaDoc文档的注释用 /** 注释内容 */
JavaDoc工具只处理文档源文件在类、接口、方法、成员变量、构造器和内部类之前的注释，忽略其他地方的文档注释，最后形成一个和源代码配套的 API 帮助文档。相当于产品说明书，只介绍那些供用户使用的接口等部分。

简单说，傻瓜式用户说明书生成器（只拉走最外层注释，快速介绍程序外壳的input ouput数据要求，内部程序怎么走完全不介绍)

方法一：手动生成JavaDoc

terminal命令格式

javadoc [options] [packagenames] [sourcefilenames] [-subpackages pkg1:pkg2:...] [@argfiles]

对格式的说明：

    options 表示 Javadoc 命令的选项。
    packagenames 表示包名。
    sourcefiles 表示源文件名。
    -subpackages pkg1:pkg2:…：从指定包中的源文件并在其子包中递归生成文档。
    @argfiles：一个或多个文件，其中包含以任何顺序排列的 Javadoc 选项、包名和源文件名列表。

比如可以写

@Author 作者名
@version 版本号
@since 指明需要最早使用的jdk版本
@param 参数名
@return 返回值的情况
@throws 异常抛出情况

参考文献：https://zhuanlan.zhihu.com/p/599276419
也可参阅 javedoc -help

javadoc生成举例，比如文件源程序是这样：

/**
 * 本例对左右移动和++进行了实例详解
 * @author Dear_喜阳阳
 * @version 666.666
 * @since 123.45.16.666
 */
public class test_jan{
        /**
         * class里本例对左右移动和++进行了实例详解
         * class里程序定义了参数a=1427，程序定义了参数b=6，这个程序介绍了a++，++a，+a的区别
         * @param m class里程序定义了参数m，最终它m等于a
         * @param n class里程序定义了参数n，最终它n等于b
         *
         *
         */
public static void main(int n, int m) {

/**
          * 本例对左右移动和++进行了实例详解
                * @param a main里面程序定义了参数a=1427
                * @param b main里面程序定义了参数b=6
                * @return main里面sum m和n之间那个大的数
                * main里面这个程序介绍了a++，++a，+a的区别
                */



        int a=1427;//010110010011,2623₈ = 1427₁₀ = 593₁₆
        int b=6;//0110
        System.out.println(a>>+b);
        n = a;
        m = b;
        int sum = 0 ;
        //这里面级别高的+b，等于b=0+b，计算完毕结果还是6,然后给a右移6位，得到010110即就是22
        //注意：++b b++ 和 +b是完全不一样的
        System.out.println("b="+b); //b等于6
        System.out.println("+b="+(+b));//b=0+b;所以现在b是6
        System.out.println("++b="+(++b));//b=1+b;立刻赋值给b，所以现在b=7
        System.out.println("b++="+(b++));//b直接赋值b，然后再加一，所以这一行的值是7,但是b已经变成8了
        System.out.println("b="+b);
        System.out.println(a);
        System.out.println("=====>>>>");
        System.out.println(m);
        System.out.println(n);
        sum=(m>n)? m:n;
        return sum;

        }

}

现在在terminal里面输入 类似这样的指令
javadoc -encoding UTF-8 -charset UTF-8 Doc.java
我们这里输入
javadoc -encoding UTF-8 -charset UTF-8 /home/dx/javadir/java_study/src/test_jan.java

现在test_jan.java就会拥有了自己的html配套注释文件，他在当前目录下，叫做index.html，用firefox或者其他浏览器双击生成的index.html文件夹，在你的IE explorer里观察生成的注释。

方法二
使用IDEA生成javadoc文档:

1. 在IDEA中选择工具（Tool）选项卡打开
   

2. 选择生成JavaDoc
   第一步：选择生成JavaDoc文档的范围，我只对一个源文件生成Doc，所以选择文件。
   第二步：输出目录最好新建一个文件夹，比较有条理和整洁
   第三步：区域设置，决定文档的语言，简体中文就是zh_CN、繁体(台湾)zh_tw、繁体(香港)zh-hk、英语(香港)en-hk、英语(美国)en-us、英语(英国)en-gb、英语(全球)en-ww
   第四步：其他命令行参数：如果区域设置为中国，参数一般为-encoding UTF-8 -charset UTF-8
   第五步：设置完成后点击确定即可生成Doc文档

3. 查看JavaDoc文档

打开输出目录，就可看到成功生成，打开 index.html 便能看生成的文档。