Java基础语法11 - 包基制

1. Java的包机制：

Java 包机制，本质上是为了更好地组织类，而提供了一种命名机制，而这种机依赖类名命名方式。包你可以简单的理解为Windows 中的文件夹。

包语句的语法格式为：

package package1[. package2[. package3...]];

好处：

  • 方便类型的查找与使用
  • 避免命名冲突
  • 控制访问

坏处：

使用package package1时，就要求此份.java文件必须保存在package1/目录下，这样Java解释器才能找到它，否则报错。

2. 如何定义包：

  • 包名一律使用小写字母。
  • 公司使用反转的 互联网域名 作为编写的包名的开始。

    eg：com.example.aaa下的Hello类。

  • 公司内部如果发生类命名冲突，可以使用region或项目名。

    eg：com.example.region.aaa下的Hello类。

  • java语言中的包，使用java、javax。

Java基础语法11-12 - 包基制（JavaDoc）如果 互联网域名 因一些特殊原因无法使用，可以使用下划线将域名转化成可以使用的类型。

eg：域名中包含-，域名中包含保留字等。

Java基础语法11-12 - 包基制（JavaDoc）

而为了能够使用某一个包的成员，我们需要在Java程序中明确导入该包。

3. 使用“import”语句导入包：

import package1[.package2...].(classname|*);

如：

import aaa.Hello ; //引用aaa package 下的 Hello类型

注意：

  • import语句是在package后，class语句之前。
  • import引入的类型，使用时无需再用完成的类型名。

4. 包看上去分层，实际并不分层

如 java.awt、java.awt.color、java.awt.font，java.awt并不包含其他两个包。所以，即使引入了java.awt，也不会引入其他两个包内的类型。

其他两个包使用java.awt作为包前缀，可以表示这三个包在功能上是互相关联的，但也仅此而已。

Java 基础语法12 - JavaDoc生成文档

  • Javadoc命令是用来生成自己的API文档的

A. 使用Javadoc 命令生成文档：

  1. 格式如下：
# javadoc生成文档命令 
# -encoding UTF-8 -charset UTF-8是为了更好的支持中文
javadoc -encoding UTF-8 -charset UTF-8 Doc.java
  1. 生成文档可加入的参数信息
@author 作者名
@version 版本号
@since 指明需要最早使用的jdk版本
@param 参数名
@retrun 返回值情况
@throuws 异常抛出情况

示例：

package com.zctou.operator;
//类的注释 @since 1.8 是指版本从1.8开始
/**
 * @author Zctou
 * @version 1.0
 * @since 1.8
 */
public class Doc {
    
    String name;
    //方法里就是方法的注释,方法上自动生成一些参数
    /**
     * @author Zctou
     * @param name
     * @return
     * @throws Exception
     */
    public String test(String name) throws Exception{
        return name;
    }
}

结果：

IDEA中，如何找到文件所在位置：

  1. 在IDEA中找到相应的文件，鼠标右键 -> Open In -> Exploerer。
    -Java基础语法11-12 - 包基制（JavaDoc）

  2. 打开资源管理器后，地址栏快捷打开CMD，输入javadoc命令生成文档。

    • 键入命令：

      javadoc -encoding UTF-8 -charset UTF-8 Doc.java

    • CMD结果：

      ...
正在构造 Javadoc 信息...
标准 Doclet 版本 1.8.0_202
正在构建所有程序包和类的树...
正在生成.\com\zctou\operator\Doc.html...
Doc.java:14: 警告: @param 没有说明
     * @param name
       ^
Doc.java:15: 警告: @return 没有说明
     * @return
       ^
Doc.java:16: 警告: @throws 没有说明
     * @throws Exception
       ^
正在生成.\com\zctou\operator\package-frame.html...
正在生成.\com\zctou\operator\package-summary.html...
正在生成.\com\zctou\operator\package-tree.html...
正在生成.\constant-values.html...
正在构建所有程序包和类的索引...
正在生成.\overview-tree.html...
正在生成.\index-all.html...
正在生成.\deprecated-list.html...
正在构建所有类的索引...
正在生成.\allclasses-frame.html...
正在生成.\allclasses-noframe.html...
正在生成.\index.html...
...

      可以看到，javadoc多生成了一堆html文件。
      Java基础语法11-12 - 包基制（JavaDoc）

B. 使用IDEA生产JavaDoc文档

  1. 选中要生成文档的代码， Tools -> Gerenate JavaDoc，弹出生成文档的对话框。

    Java基础语法11-12 - 包基制（JavaDoc）

  2. 对话框内填入相应的内容

    Java基础语法11-12 - 包基制（JavaDoc）

    可以看到，下面有三个可填选项,全部是可选选项：
    1. Locale ：，表示的是需要生成的 JavaDoc 以何种语言版本展示，如果不填，默认可能是英文或者是当前操作系统的语言，这里肯定填 zh_CN，支持中文。
    2. Other command line arguments: 这里非常重要，是直接填写向 javadoc.exe 传递的参数内容。为了更好的支持中文，这里填入：-encoding UTF-8 -charset UTF-8
    3. 官方参考文档

输出结果：

D:\Evn\Java\jdk1.8.0_202\bin\javadoc.exe -locale zh_CN -protected -splitindex -use -author -version -encoding UTF-8 -charset UTF-8 -d D:\MyCode\JavaSE\基础语法\src\com\zctou\operator\idea_doc @C:\Users\Administrator\AppData\Local\Temp\javadoc_args
   正在加载源文件D:\MyCode\JavaSE\基础语法\src\com\zctou\operator\Doc.java...
   正在构造 Javadoc 信息...
   标准 Doclet 版本 1.8.0_202
   正在构建所有程序包和类的树...
   正在生成D:\MyCode\JavaSE\基础语法\src\com\zctou\operator\idea_doc\com\zctou\operator\Doc.html...
   D:\MyCode\JavaSE\基础语法\src\com\zctou\operator\Doc.java:14: 警告: @param 没有说明
 * @param name
   ^
   D:\MyCode\JavaSE\基础语法\src\com\zctou\operator\Doc.java:15: 警告: @return 没有说明
 * @return
   ^
   D:\MyCode\JavaSE\基础语法\src\com\zctou\operator\Doc.java:16: 警告: @throws 没有说明
 * @throws Exception
   ^
   正在生成D:\MyCode\JavaSE\基础语法\src\com\zctou\operator\idea_doc\com\zctou\operator\package-frame.html...
   正在生成D:\MyCode\JavaSE\基础语法\src\com\zctou\operator\idea_doc\com\zctou\operator\package-summary.html...
   正在生成D:\MyCode\JavaSE\基础语法\src\com\zctou\operator\idea_doc\com\zctou\operator\package-tree.html...
   正在生成D:\MyCode\JavaSE\基础语法\src\com\zctou\operator\idea_doc\constant-values.html...
   正在生成D:\MyCode\JavaSE\基础语法\src\com\zctou\operator\idea_doc\com\zctou\operator\class-use\Doc.html...
   正在生成D:\MyCode\JavaSE\基础语法\src\com\zctou\operator\idea_doc\com\zctou\operator\package-use.html...
   正在构建所有程序包和类的索引...
   正在生成D:\MyCode\JavaSE\基础语法\src\com\zctou\operator\idea_doc\overview-tree.html...
   正在生成D:\MyCode\JavaSE\基础语法\src\com\zctou\operator\idea_doc\index-files\index-1.html...
   正在生成D:\MyCode\JavaSE\基础语法\src\com\zctou\operator\idea_doc\index-files\index-2.html...
   正在生成D:\MyCode\JavaSE\基础语法\src\com\zctou\operator\idea_doc\index-files\index-3.html...
   正在生成D:\MyCode\JavaSE\基础语法\src\com\zctou\operator\idea_doc\deprecated-list.html...
   正在构建所有类的索引...
   正在生成D:\MyCode\JavaSE\基础语法\src\com\zctou\operator\idea_doc\allclasses-frame.html...
   正在生成D:\MyCode\JavaSE\基础语法\src\com\zctou\operator\idea_doc\allclasses-noframe.html...
   正在生成D:\MyCode\JavaSE\基础语法\src\com\zctou\operator\idea_doc\index.html...
   正在生成D:\MyCode\JavaSE\基础语法\src\com\zctou\operator\idea_doc\help-doc.html...
   3 个警告
可以看到，生成的Html文件全在上面指定的输出文件夹idea_doc中，非常方便。