Java语言是一门强类型语言。强类型包含两方面的含义:(1)所有的变量必须先声明、后使用。 (2)指定类型的变量只能接受类型与之匹配的值。强类型语言可以在编译过程中发现源代码的错误,从而保证程序更加健壮。
4.1 注释
!!! 记住,一定要多写注释
4.1.1 单行注释
public class Commentest
{
//单行注释
public static void main(string[] args)
{
//单行注释输出
System.out.println("Hello World");
}
}
4.1.2 多行注释
public class Commentest
{
/*
多行注释
哈哈哈
*/
public static void main(string[] args)
{
System.out.println("Hello World");
}
}
注释不仅可以给人思路,还可以debug,把语句注释,运行看看是不是这个语句所产生的错误。
4.1.3 Java 9 增强文档注释
相信单行注释,多行注释大家听过了。但Java还有这一种更加牛逼额的注释:文档注释。如果编写Java源代码时添加了合适的文档注释,然后JDK提供的javadoc工具可以直接将源代码里的文档注释提取成一份系统的API文档。
API文档是啥?其实就是在你开发一个大型号的软件的时候,要定义几千几万各类,这时候是不是需要一份说明文档,用于说明每个类、每个方法的用途。当其他人使用一个类或一个方法时,他无须关心这个类或方法的具体实现,他只要知道这个类或方法的功能即可,然后使用这个这个类或方法来实现具体目的,也就是通过调用应用程序接口(API)来编程。API文档就是用以说明这些应用程序接口的文档。
大家可以到Java的官方网站去下载API文档。这里我就不写了,网上博客特别多。下载好后点打开/docs/api 路径下,打开index.html 即可。长相大概如下图所示。
好像已经到了Java14去了,太快了,具体api文档的内容我也不是特别了解,等我以后稍微了解之后再来写一写。
同样,在开发中定义类、方法时也可以添加文档注释,然后使用javadoc工具来生成自己API文档。
问题来了,API文档重不重要?
毫无疑问,API是Java提供的基本编程接口,当使用Java语言进行编程时,不可能把所有的Java类、所有方法都记下来,当编程遇到不会的地方,就可以查找。所以,查看API文档的方法是学习Java的一个最基本的技能。
文档注释以斜线后紧跟两个星号(/**)开始,以星号后紧跟一个斜线(*/)结束,中间部分全部都是文档注释,会被提到API文档中。
例如,下面先编写一个JavadocTest类,这个类里包含了对类、方法、成员变量的文档注释。
下面我们来尝试一下:
(一):编写一个 JavadocTest.java类:
package lee;
/**
* Description:
* 网站:<a href="https://blog.csdn.net/qq_43634001/article/details/105702218">Java语言概述与开发</a><br>
* Copyright (C), 2020, Li Weile<br>
* This program is testing the funtion of javadoc. <br>
* Program Name: test_javadoc <br>
* Date: 2020-04-25 <br>
* @author LiWeile 664006035@qq.com
* @version 1.0
*/
public class JavadocTest
{
/**
* 简单测试成员变量
*/
protected String name;
/**
* 主方法:程序的入口
*/
public static void main(String[] args)
{
System.out.println("Hello World!");
}
}
(二):编写一个 Test.java
package yeeku;
/**
* Description:
* 网站:<a href="https://blog.csdn.net/qq_43634001/article/details/105702218">Java语言概述与开发</a><br>
* Copyright (C), 2020, Li Weile<br>
* This program is testing the funtion of javadoc. <br>
* Program Name: test_javadoc <br>
* Date: 2020-04-25 <br>
* @author LiWeile 664006035@qq.com
* @version 1.0
*/
public class Test
{
/**
* 简单测试成员变量
*/
public int age;
/**
* Test 类的测试构造器
*/
public Test()
{
}
}
(三)输入javadoc命令
javadoc -d apidoc -windowtitle Test -doctitle learnJavadocTestAPIdocument -header my_class *Test.java
这里一定要主意好空格,书里面的有点印刷问题,会报错。可以看到如下输出,点开自己写的包:
这样就可以看到自己的API文档了,是有点儿牛逼的亚子。
javadoc命令的基本用法如下:
javadoc 选项 Java 源文件|包
javadoc命令可对源文件、包生成API文档,在上面的语法格式中,Java源文件可以支持通配符,例如:使用 *.java 来代表当前路径下所有的Java源文件。Javadoc的常用选项有如下几个:
- -d :该选项指定一个路径,用于将生成的API文档放到指定目录下
- windowtitle
:该选项指定一个字符串,用于设置API文档的浏览器窗口标题 - doctitle:该选项指定一个HTML格式的文本,用于指定概述页面的标题。(注意:只有对处于多个包下的源文件来生成API文档时,才有概述页面)
- header:该选项指定一个HTML格式的文本,包含每个页面的页眉。
除此之外,javadoc命令还包含了大量其他选项,读者可以通过在命令行窗口执行javadoc -help 来查看javadoc 命令的所有选项。
除此之外,如果希望javadoc工具生成更详细的文档信息,例如为方法参数、方法返回值等生成详细的说明信息,则可利用javadoc标记。常用的javadoc标记如下:
- @author:指定Java程序的作者
- @version:指定源文件的版本
- @deprecated:不推荐使用的方法
- @param:方法的参数说明信息
- @return:方法的返回值说明信息
- @see:“参见”,用于指定交叉参考的内容
- @exception:抛出异常的类型
- @throws:抛出的异常和@exception同义。
需要指出的是:这些标记的使用是有位置限制的。上面这些标记可以出现在类或者接口文档注释中的有@see、@deprecated、@author、@version 等;可以出现在方法或构造器文档注释中的有@see、@deprecated、@param、@return、@throws、和@exception等。可以出现在成员变量的文档注释中有@see和@deprecated等。
我们再写一个文件,包含一个hello方法,该方法的文档注释使用了@param和@return等文档标记。文件名叫JavadocTagTest.java
package yeeku;
/**
* Description:
* 网站:<a href="https://blog.csdn.net/qq_43634001/article/details/105702218">Java语言概述与开发</a><br>
* Copyright (C), 2020, Li Weile<br>
* This program is testing the funtion of javadoc. <br>
* Program Name: test_javadoc <br>
* Date: 2020-04-25 <br>
* @author LiWeile 664006035@qq.com
* @version 1.0
*/
public class JavadocTagTest
{
/**
* 一个得到打招呼字符串的方法
* @param name 该参数指定向谁打招呼
* @return 返回打招呼的字符串
*/
public String hello(String name)
{
return name + ",你好!";
}
}
上面程序中粗体字标识出使用javadoc标记的示范,再次使用javadoc工具来生成API文档,这次为了能够提取到文档中的@author 和@version 等标记信息,再使用javadoc 工具时增加-author 和 -version两个选项,即按如下格式来运行:
javadoc -d apidoc -windowtitle 测试 -doctitle 学习 javadoc 工具c的测试API文档 -header 我的类 -version -author *Test.java
可以看到:
接下来还是使用上面编写的三个java文件,但是把三个Java文件按包结构分开组织存放,并提供对应的包描述文件,源文件和对应包描述文件的组织结构如下:
- lee 文件夹:包含JavadocTest.java 文件(该Java类的包为lee),对应描述包文件package.html
- yeeku 文件夹: 包含Test.java 文件和JavadocTagTest.java 文件(这两个Java类的包为yeeku),对应包描述文件package.html
在命令行窗口进入lee和yeeku所在路径(package路径),执行如下:
javadoc -d apidoc -windowtitle 测试 -doctitle 学习javadoc工具的测试API文档 -header 我的类 -version -author lee yeeku
上面的命令指对lee包和yeeku包来生成API文档,而不是对Java源文件来生成API文档,这也是允许的。其中lee包和yeeku包下面都提供对应的包描述文件。打开页面:
通常稍微大一点的软件目录一般都需要用最后这种API文档生成的方法。记住即可。