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代码
### 关于 Javadoc 未生成注释的原因及解决方案 当使用 `javadoc` 命令尝试生成文档时,如果发现没有生成预期的注释内容,可能是由于以下几个原因造成的: #### 1. 注释格式不正确 Javadoc 工具仅识别特定格式的注释,即以 `/**` 开头并以 `*/` 结束的注释[^2]。如果 Java 文件中的注释不符合这种格式,则不会被 Javadoc 处理。 #### 2. 缺少必要的注解标签 即使注释采用了正确的格式,但如果缺少一些常用的 Javadoc 标签(如 `@param`, `@return`, 或者 `@throws`),可能导致生成的内容不够全面或者完全缺失。虽然这不是强制性的,但在复杂场景下推荐使用这些标签来增强文档质量[^4]。 #### 3. 字符编码问题 在某些情况下,尤其是涉及中文或其他非 ASCII 字符时,可能会遇到编码错误,比如 “编码 GBK 的不可映射字符”。这通常可以通过指定 `-encoding UTF-8 -charset UTF-8` 参数解决[^4]。例如,在运行 `javadoc` 命令时加入以下选项: ```bash javadoc -encoding UTF-8 -charset UTF-8 *.java ``` #### 4. 源文件路径或名称匹配不当 确保输入给 `javadoc` 的通配符模式能够正确找到目标 `.java` 文件。如果指定了某个具体的文件名却拼写错误,或是试图通过通配符处理整个目录但忽略了子目录结构,都将导致无任何输出。对于单个文件可直接调用其全名;而对于多个文件则需注意当前工作目录以及可能存在的嵌套层次[^1]。 #### 5. 特殊情况下的包级注释遗漏 要为一个完整的软件包创建描述性说明,除了常规类级别的注释外还需要额外准备专门针对该包本身的独立注释文件——要么命名为 `package.html` 并置于相应位置,其中 `<body>` 部分会被提取作为摘要显示;要么定义名为 `package-info.java` 的特殊形式源码单元[^5]。如果没有设置这两种之一的话,那么即便其他部分正常也可能看不到有关整体架构层面的信息呈现出来。 综上所述,为了成功利用 Javadoc 自动生成详尽的技术参考资料,请仔细核查以上提到的各项要素是否存在偏差,并按照提示调整参数配置直至满足需求为止。 ```python # 示例 Python 脚本展示如何自动化执行带参数的 shell 命令 (假设环境支持 subprocess 库) import subprocess def generate_javadocs(source_files, output_dir="docs", encoding="UTF-8"): try: result = subprocess.run( ["javadoc", "-d", output_dir, "-sourcepath", ".", "-subpackages", source_files, "-encoding", encoding, "-charset", encoding], check=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE ) print(result.stdout.decode()) except subprocess.CalledProcessError as e: print(f"An error occurred while generating javadocs:\n{e.stderr.decode()}") if __name__ == "__main__": generate_javadocs("com/example/**/*.java") # 替换实际项目路径表达式 ```
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值