java入门概述

Java 语言

跟任何编程语言一样,Java 语言拥有自己的结构、语法规则和编程范例。Java 语言的编程范例基于面向对象编程 (OOP) 的概念,该语言的特性支持这一概念。

Java 语言是 C 语言的一种衍生语言,所以它的语法规则与 C 语言的语法规则非常相似。例如,方法使代码模块化并使用花括号({ 和 })分隔,变量需要在使用之前声明。

在结构上,Java 语言以 作为开头。包是 Java 语言的命名空间机制。包中包含类,而类中包含方法、变量、常量等。您将在本学习路径中了解 Java 语言的各个部分。

Java 编译器

在 Java 平台编写程序时,您会在 .java 文件中编写源代码,然后编译它们。编译器针对语言的语法规则来检查代码,然后将字节码 写出到 .class 文件中。字节码是一组需要在 Java 虚拟机 (JVM) 上运行的指令。添加了这一抽象级别后,Java 编译器不同于其他语言编译器,其他编译器会写出适合运行程序的 CPU 芯片集的汇编语言指令。

JVM

在运行时,JVM 读取并解释 .class 文件,在编写的 JVM 的目标原生硬件平台上执行程序的指令。JVM 解释字节码就像 CPU 解释汇编语言指令一样。不同之处在于,JVM 是一个专为特定平台编写的软件。JVM 是 Java 语言的 “编写一次、随处运行” 原则的核心。您的代码可在任何拥有合适的 JVM 实现的芯片集上运行。JVM 可用于 Linux 和 Windows 等主要平台,在针对移动电话和爱好者芯片的 JVM 中也已实现了 Java 语言的子集。

垃圾收集器

Java 平台不会强制您时刻关注内存分配(或使用第三方库来完成此工作),它提供了开箱即用的内存管理功能。当您的 Java 应用程序在运行时创建一个对象实例时,JVM 会自动从 中为该对象分配内存空间— 堆是一个专门留给您的程序使用的内存池。Java 垃圾收集器 在后台运行,跟踪记录应用程序不再需要哪些对象并从它们回收内存。这种内存处理方法称为隐式内存管理,因为它不需要您编写任何内存处理代码。垃圾收集是 Java 平台性能的基本特征之一。

Java 开发工具包

下载 Java 开发工具包 (JDK),您会获得 — 包括编译器和其他工具 — 包含预构建的实用程序的完整类库,以帮助您完成最常见的应用程序开发任务。了解 JDK 包和库的范围的最佳方式是查阅 官方在线 Java API 文档— 也称为 Javadoc。可观看这个快速演示,了解如何浏览 Javadoc。

Java 运行时环境

Java 运行时环境(JRE;也称为 Java 运行时)包含 JVM、代码库和运行以 Java 语言编写的程序所必要的组件。JRE 可用于多种平台。您可依据 JRE 许可条款,在您的应用程序中自由地重新分发 JRE,为应用程序的用户提供一个运行您的软件的平台。JRE 包含在 JDK 中。


建议《Effective Java》、《Java编程思想》以及《重构:改善既有代码质量》是Java程序员必看书籍

1、java 值传递与 引用传递。【 深拷贝 与 浅拷贝 问题】

2、String 类问题

3、java 访问权限问题。【类的权限  和 类方法类变量的权限】

来自:https://www.ibm.com/developerworks/cn/java/j-perry-java-platform-overview/index.html

java入门概述-MANIFEST.MF文件详解及编写规范

参考百度百科的解释如下:

http://baike.baidu.com/item/MANIFEST.MF

MANIFEST.MF:这个 manifest 文件定义了与扩展和包相关的数据。单词“manifest”的意思是“显示”

打开Java的JAR文件我们经常可以看到文件中包含着一个META-INF目录,这个目录下会有一些文件,其中必有一个MANIFEST.MF,这个文件描述了该Jar文件的很多信息,下面将详细介绍MANIFEST.MF文件的内容,先来看struts.jar中包含的MANIFEST.MF文件内容:

Manifest-Version: 1.0

Created-By: Apache Ant 1.5.1

Extension-Name: Struts Framework

Specification-Title: Struts Framework

Specification-Vendor: Apache Software Foundation

Specification-Version: 1.1

Implementation-Title: Struts Framework

Implementation-Vendor: Apache Software Foundation

Implementation-Vendor-Id: org.apache

Implementation-Version: 1.1

Class-Path: commons-beanutils.jar commons-collections.jar commons-digester.jar commons-logging.jar commons-validator.jar jakarta-oro.jar struts-legacy.jar

如果我们把MANIFEST中的配置信息进行分类,可以归纳出下面几个大类:

一. 一般属性

1. Manifest-Version

用来定义manifest文件的版本,例如:Manifest-Version: 1.0

2. Created-By

声明该文件的生成者,一般该属性是由jar命令行工具生成的,例如:Created-By: Apache Ant 1.5.1

3. Signature-Version

定义jar文件的签名版本

4. Class-Path

应用程序或者类装载器使用该值来构建内部的类搜索路径

二. 应用程序相关属性

1. Main-Class

定义jar文件的入口类,该类必须是一个可执行的类,一旦定义了该属性即可通过 java -jar x.jar来运行该jar文件。

三. 小程序(Applet)相关属性

1. Extendsion-List

该属性指定了小程序需要的扩展信息列表,列表中的每个名字对应以下的属性

2. <extension>-Extension-Name

3. <extension>-Specification-Version

4. <extension>-Implementation-Version

5. <extension>-Implementation-Vendor-Id

5. <extension>-Implementation-URL

四. 扩展标识属性

1. Extension-Name

该属性定义了jar文件的标识,例如Extension-Name: Struts Framework

五. 包扩展属性

1. Implementation-Title 定义了扩展实现的标题

2. Implementation-Version 定义扩展实现的版本

3. Implementation-Vendor 定义扩展实现的组织

4. Implementation-Vendor-Id 定义扩展实现的组织的标识

5. Implementation-URL : 定义该扩展包的下载地址(URL)

6. Specification-Title 定义扩展规范的标题

7. Specification-Version 定义扩展规范的版本

8. Specification-Vendor 声明了维护该规范的组织

9. Sealed 定义jar文件是否封存,值可以是true或者false (这点我还不是很理解)

六. 签名相关属性

签名方面的属性我们可以来参照JavaMail所提供的mail.jar中的一段

Name: javax/mail/Address.class

Digest-Algorithms: SHA MD5

SHA-Digest: AjR7RqnN//cdYGouxbd06mSVfI4=

MD5-Digest: ZnTIQ2aQAtSNIOWXI1pQpw==

这段内容定义类签名的类名、计算摘要的算法名以及对应的摘要内容(使用BASE64方法进行编码)

七.自定义属性

除了前面提到的一些属性外,你也可以在MANIFEST.MF中增加自己的属性以及响应的值,例如J2ME程序jar包中就可能包含着如下信息

MicroEdition-Configuration: CLDC-1.0

MIDlet-Name: J2ME_MOBBER Midlet Suite

MIDlet-Info-URL: http://www.javayou.com/

MIDlet-Icon: /icon.png

MIDlet-Vendor: Midlet Suite Vendor

MIDlet-1: mobber,/icon.png,mobber

MIDlet-Version: 1.0.0

MicroEdition-Profile: MIDP-1.0

MIDlet-Description: Communicator

关键在于我们怎么来读取这些信息呢?其实很简单,JDK给我们提供了用于处理这些信息的API,详细的信息请见java.util.jar包中,我们可以通过给JarFile传递一个jar文件的路径,然后调用JarFile的getManifest方法来获取Manifest信息。

备注:更详细的说明,参考oracle提供的文档:http://docs.oracle.com/javase/1.5.0/docs/guide/jar/jar.html(这个地址其实是有规律的,试下后面的版本号更新到特定的)

 

编写MANIFEST.MF文件时的注意事项:

说明:一般编写MANIFEST.MF文件只需要用到Manifest-Version(MF文件版本号)、Main-Class(包含main方法的类)、Class-Path(执行这个jar包时的ClassPath,第三方依赖)

比如以下的例子:

Manifest-Version: 1.0 
Main-Class: test.Main 
Class-Path: ./ ./lib/commons-collections-3.2.jar ./lib/commons-dbcp-1.2.2.jar ./lib/commons-lang-2.3.jar ./lib/commons-logging-1.1.jar 

以下是需要注意的各个要点:

0. 最后一样一定要回车,空一行,不然无法识别最后一行的配置。

1. Manifest-Version、Main-Class和Class-Path后面跟着一个英文的冒号,冒号后面必须跟着一个空格,然后才是版本号、类和ClassPath。

2. Class-Path中的各项应使用空格分隔,不是逗号或分号。

3. Class-Path中如果有很多项,写成一行打包的时候会报错line too long,这时需要把Class-Path分多行写。注意:从第二行开始,必须以两个空格开头,三个以上我没试过,不过不用空格开头和一个空格开头都是不行的,我已经试过了。

4. Class-Path写完之后最后一定要有一个空行

5. jar包内有些配置文件想放在jar包外面,比如文件config.properties:如果这个文件是以路径方式载入的,比如new file(“./config/config.properties”),那么将config.properties放在jar包相同目录下的config目录下即可,也就是说“./”路径等价于jar包所在目录;如果这个文件是以ClassPath下的文件这种方式载入的,比如在Spring中载入classpath:config.properties,则在MF文件的配置文件的ClassPath中添加“./”,然后将这个配置文件与jar包放在同一个目录即可,当然也可以在MF文件的配置文件的ClassPath中添加“./config/”,然后把配置文件都放在jar包相同目录下的config目录下。

参考:http://www.cnblogs.com/gaoguofeng/p/5646442.html

来自:https://www.cnblogs.com/EasonJim/p/6485677.html

java入门概述-META-INF文件夹的含义

在java web 开发 和 安卓开发中,我们在打包文件的时候,经常能看到 META-INF文件夹。里面也存放了一些文件,那这个到底是干什么的呢。我们来了解一下:

首先查看 java 官方api 文档:
https://docs.oracle.com/javase/7/docs/technotes/guides/jar/jar.html#The_META-INF_directory

参考连接:

https://stackoverflow.com/questions/70216/whats-the-purpose-of-meta-inf


The META-INF directory
The following files/directories in the META-INF directory are recognized and interpreted by the Java 2 Platform to configure applications, extensions, class loaders and services:

MANIFEST.MF
The manifest file that is used to define extension and package related data.

INDEX.LIST
This file is generated by the new “-i” option of the jar tool, which contains location information for packages defined in an application or extension. It is part of the JarIndex implementation and used by class loaders to speed up their class loading process.

x.SF
The signature file for the JAR file. ‘x’ stands for the base file name.

x.DSA
The signature block file associated with the signature file with the same base file name. This file stores the digital signature of the corresponding signature file.

services/
This directory stores all the service provider configuration files.


百度知道解释:

常常在网上看到有人询问:如何把 java 程序编译成 .exe 文件。通常回答只有两种,一种是制作一个可执行的 JAR 文件包,然后就可以像.chm 文档一样双击运行了;而另一种是使用 JET 来进行 编译。但是 JET 是要用钱买的,而且据说 JET 也不是能把所有的 Java 程序都编译成执行文件,性能也要打些折扣。所以,使用制作可执行 JAR 文件包的方法就是最佳选择了,何况它还能保持 Java 的跨平台特性。

下面就来看看什么是 JAR 文件包吧:

1. JAR 文件包

JAR 文件就是 Java Archive File,顾名思意,它的应用是与 Java 息息相关的,是 Java 的一种文档格式。JAR 文件非常类似 ZIP 文件——准确的说,它就是 ZIP 文件,所以叫它文件包。JAR 文件与 ZIP 文件唯一的区别就是在 JAR 文件的内容中,包含了一个 META-INF/MANIFEST.MF 文件,这个文件是在生成 JAR 文件的时候自动创建的。举个例子,如果我们具有如下目录结构的一些文件:

==

`– test

`– Test.class

把它压缩成 ZIP 文件 test.zip,则这个 ZIP 文件的内部目录结构为:

test.zip

`– test

`– Test.class

如果我们使用 JDK 的 jar 命令把它打成 JAR 文件包 test.jar,则这个 JAR 文件的内部目录结构为:

test.jar

|– META-INF

| `– MANIFEST.MF

`– test

`–Test.class

2. 创建可执行的 JAR 文件包

制作一个可执行的 JAR 文件包来发布你的程序是 JAR 文件包最典型的用法。

Java 程序是由若干个 .class 文件组成的。这些 .class 文件必须根据它们所属的包不同而分级分目录存放;运行前需要把所有用到的包的根目录指定给 CLASSPATH 环境变量或者 java 命令的 -cp 参数;运行时还要到控制台下去使用 java 命令来运行,如果需要直接双击运行必须写 Windows 的批处理文件 (.bat) 或者 Linux 的 Shell 程序。因此,许多人说,Java 是一种方便开发者苦了用户的程序设计语言。

其实不然,如果开发者能够制作一个可执行的 JAR 文件包交给用户,那么用户使用起来就方便了。在 Windows 下安装 JRE (Java Runtime Environment) 的时候,安装文件会将 .jar 文件映射给 javaw.exe 打开。那么,对于一个可执行的 JAR 文件包,用户只需要双击它就可以运行程序了,和阅读 .chm 文档一样方便 (.chm 文档默认是由 hh.exe 打开的)。那么,现在的关键,就是如何来创建这个可执行的 JAR 文件包。

创建可执行的 JAR 文件包,需要使用带 cvfm 参数的 jar 命令,同样以上述 test 目录为例,命令如下:

jar cvfm test.jar manifest.mf test

这里 test.jar 和 manifest.mf 两个文件,分别是对应的参数 f 和 m,其重头戏在 manifest.mf。因为要创建可执行的 JAR 文件包,光靠指定一个 manifest.mf 文件是不够的,因为 MANIFEST 是 JAR 文件包的特征,可执行的 JAR 文件包和不可执行的 JAR 文件包都包含 MANIFEST。关键在于可执行 JAR 文件包的 MANIFEST,其内容包含了 Main-Class 一项。这在 MANIFEST 中书写格式如下:

Main-Class: 可执行主类全名(包含包名)

例如,假设上例中的 Test.class 是属于 test 包的,而且是可执行的类 (定义了 public static void main(String[]) 方法),那么这个 manifest.mf 可以编辑如下:

Main-Class: test.Test <回车>;

这个 manifest.mf 可以放在任何位置,也可以是其它的文件名,只需要有 Main-Class: test.Test 一行,且该行以一个回车符结束即可。创建了 manifest.mf 文件之后,我们的目录结构变为:

==

|– test

| `– Test.class

`– manifest.mf

这时候,需要到 test 目录的上级目录中去使用 jar 命令来创建 JAR 文件包。也就是在目录树中使用“==”表示的那个目录中,使用如下命令:

jar cvfm test.jar manifest.mf test

之后在“==”目录中创建了 test.jar,这个 test.jar 就是执行的 JAR 文件包。运行时只需要使用 java -jar test.jar 命令即可。

需要注意的是,创建的 JAR 文件包中需要包含完整的、与 Java 程序的包结构对应的目录结构,就像上例一样。而 Main-Class 指定的类,也必须是完整的、包含包路径的类名,如上例的 test.Test;而且在没有打成 JAR 文件包之前可以使用 java <类名>; 来运行这个类,即在上例中 java test.Test 是可以正确运行的 (当然要在 CLASSPATH 正确的情况下)。

3. jar 命令详解

jar 是随 JDK 安装的,在 JDK 安装目录下的 bin 目录中,Windows 下文件名为 jar.exe,Linux 下文件名为 jar。它的运行需要用到 JDK 安装目录下 lib 目录中的 tools.jar 文件。不过我们除了安装 JDK 什么也不需要做,因为 SUN 已经帮我们做好了。我们甚至不需要将 tools.jar 放到 CLASSPATH 中。

使用不带任何的 jar 命令我们可以看到 jar 命令的用法如下:

jar {ctxu}[vfm0M] [jar-文件] [manifest-文件] [-C 目录] 文件名 …

其中 {ctxu} 是 jar 命令的子命令,每次 jar 命令只能包含 ctxu 中的一个,它们分别表示:

-c 创建新的 JAR 文件包

-t 列出 JAR 文件包的内容列表

-x 展开 JAR 文件包的指定文件或者所有文件

-u 更新已存在的 JAR 文件包 (添加文件到 JAR 文件包中)

[vfm0M] 中的选项可以任选,也可以不选,它们是 jar 命令的选项参数

-v 生成详细报告并打印到标准输出

-f 指定 JAR 文件名,通常这个参数是必须的

-m 指定需要包含的 MANIFEST 清单文件

-0 只存储,不压缩,这样产生的 JAR 文件包会比不用该参数产生的体积大,但速度更快

-M 不产生所有项的清单(MANIFEST〕文件,此参数会忽略 -m 参数

[jar-文件] 即需要生成、查看、更新或者解开的 JAR 文件包,它是 -f 参数的附属参数

[manifest-文件] 即 MANIFEST 清单文件,它是 -m 参数的附属参数

[-C 目录] 表示转到指定目录下去执行这个 jar 命令的操作。它相当于先使用 cd 命令转该目录下再执行不带 -C 参数的 jar 命令,它只能在创建和更新 JAR 文件包的时候可用。

文件名 … 指定一个文件/目录列表,这些文件/目录就是要添加到 JAR 文件包中的文件/目录。如果指定了目录,那么 jar 命令打包的时候会自动把该目录中的所有文件和子目录打入包中。

下面举一些例子来说明 jar 命令的用法:

1) jar cf test.jar test

该命令没有执行过程的显示,执行结果是在当前目录生成了 test.jar 文件。如果当前目录已经存在 test.jar,那么该文件将被覆盖。

2) jar cvf test.jar test

该命令与上例中的结果相同,但是由于 v 参数的作用,显示出了打包过程,如下:

标明清单(manifest)

增加:test/(读入= 0) (写出= 0)(存储了 0%)

增加:test/Test.class(读入= 7) (写出= 6)(压缩了 14%)

3) jar cvfM test.jar test

该命令与 2) 结果类似,但在生成的 test.jar 中没有包含 META-INF/MANIFEST 文件,打包过程的信息也略有差别:

增加:test/(读入= 0) (写出= 0)(存储了 0%)

增加:test/Test.class(读入= 7) (写出= 6)(压缩了 14%)

4) jar cvfm test.jar manifest.mf test

运行结果与 2) 相似,显示信息也相同,只是生成 JAR 包中的 META-INF/MANIFEST 内容不同,是包含了 manifest.mf 的内容

5) jar tf test.jar

在 test.jar 已经存在的情况下,可以查看 test.jar 中的内容,如对于 2) 和 3) 生成的 test.jar 分别应该此命令,结果如下;

对于 2)

META-INF/

META-INF/MANIFEST.MF

test/

test/Test.class

对于 3)

test/

test/Test.class

6) jar tvf test.jar

除显示 5) 中显示的内容外,还包括包内文件的详细信息,如:

0 Wed Jun 19 15:39:06 GMT 2002 META-INF/

86 Wed Jun 19 15:39:06 GMT 2002 META-INF/MANIFEST.MF

0 Wed Jun 19 15:33:04 GMT 2002 test/

7 Wed Jun 19 15:33:04 GMT 2002 test/Test.class

7) jar xf test.jar

解开 test.jar 到当前目录,不显示任何信息,对于 2) 生成的 test.jar,解开后的目录结构如下:

==

|– META-INF

| `– MANIFEST

`– test

`–Test.class

8) jar xvf test.jar

运行结果与 7) 相同,对于解压过程有详细信息显示,如:

创建:META-INF/

展开:META-INF/MANIFEST.MF

创建:test/

展开:test/Test.class

9) jar uf test.jar manifest.mf

在 test.jar 中添加了文件 manifest.mf,此使用 jar tf 来查看 test.jar 可以发现 test.jar 中比原来多了一个 manifest。这里顺便提一下,如果使用 -m 参数并指定 manifest.mf 文件,那么 manifest.mf 是作为清单文件 MANIFEST 来使用的,它的内容会被添加到 MANIFEST 中;但是,如果作为一般文件添加到 JAR 文件包中,它跟一般文件无异。

10) jar uvf test.jar manifest.mf

与 9) 结果相同,同时有详细信息显示,如:

增加:manifest.mf(读入= 17) (写出= 19)(压缩了 -11%)

4. 关于 JAR 文件包的一些技巧

1) 使用 unzip 来解压 JAR 文件

在介绍 JAR 文件的时候就已经说过了,JAR 文件实际上就是 ZIP 文件,所以可以使用常见的一些解压 ZIP 文件的工具来解压 JAR 文件,如 Windows 下的 WinZip、WinRAR 等和 Linux 下的 unzip 等。使用 WinZip 和 WinRAR 等来解压是因为它们解压比较直观,方便。而使用 unzip,则是因为它解压时可以使用 -d 参数指定目标目录。

在解压一个 JAR 文件的时候是不能使用 jar 的 -C 参数来指定解压的目标的,因为 -C 参数只在创建或者更新包的时候可用。那么需要将文件解压到某个指定目录下的时候就需要先将这具 JAR 文件拷贝到目标目录下,再进行解压,比较麻烦。如果使用 unzip,就不需要这么麻烦了,只需要指定一个 -d 参数即可。如:

unzip test.jar -d dest/

2) 使用 WinZip 或者 WinRAR 等工具创建 JAR 文件

上面提到 JAR 文件就是包含了 META-INF/MANIFEST 的 ZIP 文件,所以,只需要使用 WinZip、WinRAR 等工具创建所需要 ZIP 压缩包,再往这个 ZIP 压缩包中添加一个包含 MANIFEST 文件的 META-INF 目录即可。对于使用 jar 命令的 -m 参数指定清单文件的情况,只需要将这个 MANIFEST 按需要修改即可。

3) 使用 jar 命令创建 ZIP 文件

有些 Linux 下提供了 unzip 命令,但没有 zip 命令,所以需要可以对 ZIP 文件进行解压,即不能创建 ZIP 文件。如要创建一个 ZIP 文件,使用带 -M 参数的 jar 命令即可,因为 -M 参数表示制作 JAR 包的时候不添加 MANIFEST 清单,那么只需要在指定目标 JAR 文件的地方将 .jar 扩展名改为 .zip 扩展名,创建的就是一个不折不扣的 ZIP 文件了,如将上一节的第 3) 个例子略作改动:

jar cvfM test.zip test

java入门概述-javadoc.jar和-sources.jar的含义及配置

关于SpringJar包的,我在spring官网上下载了spring有关Jar包,每个都有不同的后缀,请问分别是什么意思?
比如 spring-core-4.1.2.RELEASE-javadoc.jar spring-core-4.1.2.RELEASE-sources.jar spring-core-4.1.2.RELEASE.jar 这三个包分别是代表什么???
spring-core-4.1.2.RELEASE-javadoc.jar      API

spring-core-4.1.2.RELEASE-sources.jar    源码

spring-core-4.1.2.RELEASE.jar     运行jar包

在使用Java语言开发的过程中,开发人员经常需要用到一些开源的工具包。在使用别人的jar包的时候,为了保证正常调用包内的方法需要把jar包添加到Referenced Libraries中。由于jar中通常只打包了类的二进制文件,其JavaDoc文件仍需要以浏览器或chm帮助文档的方式查看。Eclipse开发环境中提供了将JavaDoc文档附加到jar包中的功能,使开发者不再需要人工查找类或方法的JavaDoc注释,省时又省力。

①右键目标jar包,选择Properties
②选择Java Source Attachment,配置好sources的路径,然后点击OK

③再选择JavaDoc Location,配置好doc的路径,然后点击OK

完成以上步骤后,就可以轻松查看相应的源码和帮助文档了

查看源码,选中目标class,快捷键shift+f2
查看帮助文档,选中目标class,快捷键f3

参考:https://blog.csdn.net/u011998957/article/details/50592573


javadoc 和 javadoc注释规范
javadoc是Sun公司提供的一个技术,它从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。
javadoc命令是用来生成自己API文档的,使用方式:在dos中在目标文件所在目录输入javadoc +文件名.java。
标签 说明 JDK 1.1 doclet 标准doclet 标签类型
@author 作者 作者标识 包、 类、接口
@version 版本号 版本号 包、 类、接口
@param 参数名 描述 方法的入参名及描述信息,如入参有特别要求,可在此注释。 构造函数、 方法
@return 描述 对函数返回值的注释 方法
@deprecated 过期文本 标识随着程序版本的提升,当前API已经过期,仅为了保证兼容性依然存在,以此告之开发者不应再用这个API。 包、类、接口、值域、构造函数、 方法
@throws异常类名 构造函数或方法所会抛出的异常。 构造函数、 方法
@exception 异常类名 同@throws。 构造函数、 方法
@see 引用 查看相关内容,如类、方法、变量等。 包、类、接口、值域、构造函数、 方法
@since 描述文本 API在什么程序的什么版本后开发支持。 包、类、接口、值域、构造函数、 方法
{@link包.类#成员 标签} 链接到某个特定的成员对应的文档中。 包、类、接口、值域、构造函数、 方法
{@value} 当对常量进行注释时,如果想将其值包含在文档中,则通过该标签来引用常量的值。 √(JDK1.4) 静态值域
此 外还有@serial、@serialField、@serialData、{@docRoot}、{@inheritDoc}、{@literal}、 {@code} {@value arg}几个不常用的标签,由于不常使用,我们展开叙述,感兴趣的读者可以查看帮助文档。
javadoc做注释
一. Java 文档// 注释一行
/* …… */ 注释若干行
/** …… */ 注释若干行,并写入 javadoc 文档通常这种注释的多行写法如下:/**
* ………
* ………
*/

javadoc -d 文档存放目录 -author -version 源文件名.java
这条命令编译一个名为 “源文件名.java”的 java 源文件,并将生成的文档存放在“文档存放目录”指定的目录下,生成的文档中 index.html 就是文档的首页。-author 和 -version 两个选项可以省略。

二. 文档注释的格式

1. 文档和文档注释的格式化

生成的文档是 HTML 格式,而这些 HTML 格式的标识符并不是 javadoc 加的,而是我们在写注释的时候写上去的。
比如,需要换行时,不是敲入一个回车符,而是写入 <br>,如果要分段,就应该在段前写入 <p>。
文档注释的正文并不是直接复制到输出文件 (文档的 HTML 文件),而是读取每一行后,删掉前导的 * 号及 * 号以前的空格,再输入到文档的。如

/**
* This is first line. <br>
***** This is second line. <br>
This is third line.
*/

2. 文档注释的三部分
先举例如下

/**
* show 方法的简述.
* <p>show 方法的详细说明第一行<br>
* show 方法的详细说明第二行
* @param b true 表示显示,false 表示隐藏
* @return 没有返回值
*/
public void show(boolean b) {
frame.show(b);
}

第一部分是简述。文档中,对于属性和方法都是先有一个列表,然后才在后面一个一个的详细的说明
简述部分写在一段文档注释的最前面,第一个点号 (.) 之前 (包括点号)。换句话说,就是用第一个点号分隔文档注释,之前是简述,之后是第二部分和第三部分。

第二部分是详细说明部分。该部分对属性或者方法进行详细的说明,在格式上没有什么特殊的要求,可以包含若干个点号。
* show 方法的简述.
* <p>show 方法的详细说明第一行<br>
* show 方法的详细说明第二行

简述也在其中。这一点要记住了

第三部分是特殊说明部分。这部分包括版本说明、参数说明、返回值说明等。
* @param b true 表示显示,false 表示隐藏
* @return 没有返回值

三. 使用 javadoc 标记
javadoc 标记由“@”及其后所跟的标记类型和专用注释引用组成
javadoc 标记有如下一些:
@author 标明开发该类模块的作者
@version 标明该类模块的版本
@see 参考转向,也就是相关主题
@param 对方法中某参数的说明
@return 对方法返回值的说明
@exception 对方法可能抛出的异常进行说明

@author 作者名
@version 版本号
其中,@author 可以多次使用,以指明多个作者,生成的文档中每个作者之间使用逗号 (,) 隔开。@version 也可以使用多次,只有第一次有效

使用 @param、@return 和 @exception 说明方法
这三个标记都是只用于方法的。@param 描述方法的参数,@return 描述方法的返回值,@exception 描述方法可能抛出的异常。它们的句法如下:
@param 参数名 参数说明
@return 返回值说明
@exception 异常类名 说明

四. javadoc 命令
用法:
javadoc [options] [packagenames] [sourcefiles]

选项:

-public 仅显示 public 类和成员
-protected 显示 protected/public 类和成员 (缺省)
-package 显示 package/protected/public 类和成员
-private 显示所有类和成员
-d <directory> 输出文件的目标目录
-version 包含 @version 段
-author 包含 @author 段
-splitindex 将索引分为每个字母对应一个文件
-windowtitle <text> 文档的浏览器窗口标题

javadoc 编译文档时可以给定包列表,也可以给出源程序文件列表。例如在 CLASSPATH 下有两个包若干类如下:

fancy.Editor
fancy.Test
fancy.editor.ECommand
fancy.editor.EDocument
fancy.editor.EView

可以直接编译类:
javadoc fancy\Test.java fancy\Editor.java fancy\editor\ECommand.java fancy\editor\EDocument.java fancy\editor\EView.java

也可以是给出包名作为编译参数,如:javadoc fancy fancy.editor
可以自己看看这两种方法的区别

到此为止javadoc就简单介绍完了,想要用好她还是要多用,多参考标准java代码
Java代码规范
–注释

@author LEI

@version 1.10 2005-09-01
1 注释文档的格式

注释文档将用来生成HTML格式的代码报告,所以注释文档必须书写在类、域、构造函数、方法、定义之前。注释文档由两部分组成——描述、块标记。

例如:

/**

* The doGet method of the servlet.

* This method is called when a form has its tag value method equals to get.

*

* @param request

* the request send by the client to the server

* @param response

* the response send by the server to the client

* @throws ServletException

* if an error occurred

* @throws IOException

* if an error occurred

*/

public void doGet (HttpServletRequest request, HttpServletResponse response)

throws ServletException, IOException {

doPost(request, response);

}

前两行为描述,描述完毕后,由@符号起头为块标记注视。
2 注释的种类
2.1 文件头注释

文件头注释以 /*开始,以*/结束,需要注明该文件创建时间,文件名,命名空间信息。

例如:

/*

* Created on 2005-7-2

* /
2.2 类、接口注释

类、接口的注释采用 /** … */,描述部分用来书写该类的作用或者相关信息,块标记部分必须注明作者和版本。

例如:

/**Title: XXXX DRIVER 3.0
*Description: XXXX DRIVER 3.0
*Copyright: Copyright (c) 2003
*Company:XXXX有限公司
*
* @author Java Development Group
* @version 3.0
*/

例如:

/**
* A class representing a window on the screen.
* For example:
*
* Window win = new Window(parent);
* win.show();
*
*
* @author Sami Shaio
* @version %I%, %G%
* @see java.awt.BaseWindow
* @see java.awt.Button
*/

class Window extends BaseWindow {

}
2.3 构造函数注释

构造函数注释采用 /** … */,描述部分注明构造函数的作用,不一定有块标记部分。

例如:

/**

* 默认构造函数

*/

有例如:

/**

* 带参数构造函数,初始化模式名,名称和数据源类型

*

* @param schema

* Ref 模式名

* @param name

* Ref 名称

* @param type

* byVal 数据源类型

*/
2.4 域注释

域注释可以出现在注释文档里面,也可以不出现在注释文档里面。用/** … */的域注释将会被认为是注释文档热出现在最终生成的HTML报告里面,而使用/* … */的注释会被忽略。

例如:

/* 由于triger和表用一个DMSource,所以要区分和表的迁移成功标记 */

boolean isTrigerSuccess = false;

又例如:

/** 由于triger和表用一个DMSource,所以要区分和表的迁移成功标记 */

boolean isTrigerSuccess = false;

再例如:

/**

* The X-coordinate of the component.

*

* @see #getLocation()

*/

int x = 1263732;

2.5 方法注释

方法注释采用 /** … */,描述部分注明方法的功能,块标记部分注明方法的参数,返回值,异常等信息。例如:

/**

* 设置是否有外码约束

*

* @param conn

* Connection 与数据库的连接

*/
2.6 定义注释

规则同域注释。
3 注释块标记
3.1 标记的顺序

块标记将采用如下顺序:

*

* @param (classes, interfaces, methods and constructors only)

* @return (methods only)

* @exception (@throws is a synonym added in Javadoc 1.2)

* @author (classes and interfaces only, required)

* @version (classes and interfaces only, required. See footnote 1)

* @see

* @since

* @serial (or @serialField or @serialData)

* @deprecated (see How and When To Deprecate APIs)

* …

一个块标记可以根据需要重复出现多次,多次出现的标记按照如下顺序:

@author 按照时间先后顺序(chronological)

@param 按照参数定义顺序(declaration)

@throws 按照异常名字的字母顺序(alphabetically)

@see 按照如下顺序:

@see #field

@see #Constructor(Type, Type…)

@see #Constructor(Type id, Type id…)

@see #method(Type, Type,…)

@see #method(Type id, Type, id…)

@see Class

@see Class#field

@see Class#Constructor(Type, Type…)

@see Class#Constructor(Type id, Type id)

@see Class#method(Type, Type,…)

@see Class#method(Type id, Type id,…)

@see package.Class

@see package.Class#field

@see package.Class#Constructor(Type, Type…)

@see package.Class#Constructor(Type id, Type id)

@see package.Class#method(Type, Type,…)

@see package.Class#method(Type id, Type, id)

@see package
3.2 标记介绍
3.2.1 @param标记

@param后面空格后跟着参数的变量名字(不是类型),空格后跟着对该参数的描述。

在描述中第一个名字为该变量的数据类型,表示数据类型的名次前面可以有一个冠词如:a,an,the。如果是int类型的参数则不需要注明数据类型。例如:

* @param ch the char 用用来……

* @param _image the image 用来……

* @param _num 一个数字……

对于参数的描述如果只是一短语,最好不要首字母大写,结尾也不要句号。

对于参数的描述是一个句子,最好不要首字母大写,如果出现了句号这说明你的描述不止一句话。如果非要首字母大写的话,必须用句号来结束句子。(英文的句号)

公司内部添加ByRef和ByVal两个标记,例如:

* @param _image the image ByRef 用来……

说明该参数是引用传递(指针),ByVal可以省略,表示是值传递。
3.2.2 @return标记

返回为空(void)的构造函数或者函数,@return可以省略。

如果返回值就是输入参数,必须用与输入参数的@param相同的描述信息。

必要的时候注明特殊条件写的返回值。
3.2.3 @throws 标记

@throws以前使用的是@exception。

@throws的内容必须在函数的throws部分定义。
3.2.4 @author标记

类注释标记。

函数注释里面可以不出现@author。
3.2.5 @version

类注释标记。

函数注释里面可以不出现@version
3.2.6 @since

类注释标记。

标明该类可以运行的JDK版本

例如:

@since JDK1.2
3.2.7 @deprecated

由于某种原因而被宣布将要被废弃的方法。

/**

* @deprecated As of JDK 1.1, replaced by

* setBounds

* @see #setBounds(int,int,int,int)

*/
3.2.8 @link标记

语法:{@link package.class#member label}

Label为链接文字。

package.class#member将被自动转换成指向package.class的member文件的URL。
4 HTML代码的使用

在注释描述部分可以使用HTML代码。


表示段落

* ….

表示自动标号
5 注释示例

/**

* Graphics is the abstract base class for all graphics contexts

* which allow an application to draw onto components realized on

* various devices or onto off-screen images.

* A Graphics object encapsulates the state information needed

* for the various rendering operations that Java supports. This

* state information includes:

*

# * The Component to draw on

# * A translation origin for rendering and clipping coordinates

# * The current clip

# * The current color

# * The current font

# * The current logical pixel operation function (XOR or Paint)

# * The current XOR alternation color

* (see setXORMode)

*

*

* Coordinates are infinitely thin and lie between the pixels of the

* output device.

* Operations which draw the outline of a figure operate by traversing

* along the infinitely thin path with a pixel-sized pen that hangs

* down and to the right of the anchor point on the path.

* Operations which fill a figure operate by filling the interior

* of the infinitely thin path.

* Operations which render horizontal text render the ascending

* portion of the characters entirely above the baseline coordinate.

*

* Some important points to consider are that drawing a figure that

* covers a given rectangle will occupy one extra row of pixels on

* the right and bottom edges compared to filling a figure that is

* bounded by that same rectangle.

* Also, drawing a horizontal line along the same y coordinate as

* the baseline of a line of text will draw the line entirely below

* the text except for any descenders.

* Both of these properties are due to the pen hanging down and to

* the right from the path that it traverses.

*

* All coordinates which appear as arguments to the methods of this

* Graphics object are considered relative to the translation origin

* of this Graphics object prior to the invocation of the method.

* All rendering operations modify only pixels which lie within the

* area bounded by both the current clip of the graphics context

* and the extents of the Component used to create the Graphics object.

*

* @author Sami Shaio

* @author Arthur van Hoff

* @version %I%, %G%

* @since 1.0

*/

public abstract class Graphics {

/**

* Draws as much of the specified image as is currently available

* with its northwest corner at the specified coordinate (x, y).

* This method will return immediately in all cases, even if the

* entire image has not yet been scaled, dithered and converted

* for the current output device.

*

* If the current output representation is not yet complete then

* the method will return false and the indicated

* {@link ImageObserver} object will be notified as the

* conversion process progresses.

*

* @param img the image to be drawn

* @param x the x-coordinate of the northwest corner

* of the destination rectangle in pixels

* @param y the y-coordinate of the northwest corner

* of the destination rectangle in pixels

* @param observer the image observer to be notified as more

* of the image is converted. May be

* null

* @return true if the image is completely

* loaded and was painted successfully;

* false otherwise.

* @see Image

* @see ImageObserver

* @since 1.0

*/

public abstract boolean drawImage(Image img, int x, int y,

ImageObserver observer);

/**

* Dispose of the system resources used by this graphics context.

* The Graphics context cannot be used after being disposed of.

* While the finalization process of the garbage collector will

* also dispose of the same system resources, due to the number

* of Graphics objects that can be created in short time frames

* it is preferable to manually free the associated resources

* using this method rather than to rely on a finalization

* process which may not happen for a long period of time.

*

* Graphics objects which are provided as arguments to the paint

* and update methods of Components are automatically disposed

* by the system when those methods return. Programmers should,

* for efficiency, call the dispose method when finished using

* a Graphics object only if it was created directly from a

* Component or another Graphics object.

*

* @see #create(int, int, int, int)

* @see #finalize()

* @see Component#getGraphics()

* @see Component#paint(Graphics)

* @see Component#update(Graphics)

* @since 1.0

*/

public abstract void dispose();

/**

* Disposes of this graphics context once it is no longer

* referenced.

*

* @see #dispose()

* @since 1.0

*/

public void finalize() {

dispose();

}

}

来自:https://www.cnblogs.com/felix-/p/4310229.html