Java 中的 Javadoc

用特殊注释给方法写文档，让读者和工具看清它接收什么、返回什么。在 Yard.java 里写方法 add，接收 int x 和 int y，返回它们的和。把 /** */ 块直接放在 add 上方。在块里用一句短话说明做什么，再用 @param 标注每个参数，用 @return 标注结果。在 main 里打印 add(10, 2)。用 javac Yard.java 编译，再运行 java Yard。屏幕应显示 12。把命名规则留给下一页——本课是文档注释的形状，不是如何选名。

把 /** 放在方法上方

debugging 页靠打印值找错误的和。本页在干净方法上方写文档注释。打开 Yard.java。保持公共类名为 Yard。删掉会淹没文档主线的残留 println debug 标签、残留的 equals / == 演示、残留的 Machine horn 文件，以及任何键盘 Scanner。程序不得等待输入。这个演示不需要 import 行。
在 Yard 里保留一个小方法和一个短 main。文档块必须紧挨在它所描述的方法上方。收尾的 */ 与方法行之间空一行也可以。不要把块藏进 main。不要把块放在方法体下面。
注释开头在斜杠后写两颗星：
/**
然后写一句白话，说明 add 做什么。接着写标签。这样收尾：
*/
方法本身仍是普通 Java：
static int add(int x, int y) {
return x + y;
}
Javadoc 不改变 return 的工作方式。它告诉读者：在逐行读方法体之前，这个方法承诺什么。

在保存 Yard.java 的文件夹里运行 javac Yard.java。当圆括号、花括号和分号都匹配时，javac 不会写出自己的行。然后运行 java Yard——不要写成 java Yard.java。运行命令去掉 .java 结尾。文件里只保留一个公共类，使名称匹配 Yard。
屏幕显示 12。把这次运行走一遍。Java 从 Yard.main 开始。调用 add(10, 2) 进入方法时，x 为十，y 为二。return 那一行交回十二。System.out.println 写出这个数。Javadoc 块不会自己打印。块是给读者和文档工具看的。本页的入门证明，仍是写清注释后再正确运行。
一边看方法签名，一边读注释块。句子 Adds two numbers. 与 return x + y; 的工作相符。行 @param x first number 点名第一个参数。行 @param y second number 点名第二个参数。行 @return the sum of x and y 点名结果。标签拼写要精确：@param 与 @return 使用 @ 号和拉丁字母。
若你仍看到 debugging 文件留下的 x=10 和 y=2 再跟一个 8，请切到 Javadoc 教学文件并再次运行 java Yard。若你只在方法上方写 // Adds two numbers.，那是普通行注释，不是 Javadoc 块。保留双星形式 /**，让块成为文档，而不是单行备忘。
看着屏幕把规则说出来：在方法上方写文档，标注参数，标注返回值，再编译运行，证明方法仍然可用。本页不要发明长篇命名讲座。命名留给下一课。

阅读标签对照表

一张短表收住你在注释里打的三块。开头的 /** */ 标记文档块。@param 按名字描述一个参数。@return 描述方法交回的值。保持方法名为 add，调用为 add(10, 2)，让屏幕只显示一个清楚的数字。
这张表是本页的短地图。先放块。再标注输入与输出。再用 javac 和 java Yard 验证。不要猜任何注释样式都是 Javadoc。在确认程序仍打印 12 之前，不要删掉这块。

编辑时把表放在教学文件旁边。先指文件里的 @param x，再指签名里的 int x。先指 @param y，再指 int y。先指 @return，再指 return 那一行。这个对照游戏就是整套入门想法的一遍走完。读 Javadoc 的工具会找这些标签。方法体以后变长时，人类读者也用同一张地图。
若附近仍有 debugging 演示，把它们当作历史保留。本课请运行 Javadoc 教学文件，让屏幕从 add 显示 12，而不是狩猎留下的带标签 x= 行。若 javac 抱怨重复的公共类，只让 Yard 保持 public。

普通 // 不是 Javadoc

以 // 开头的行是给读文件的人看的备注。它有用，本课程前面也用过行注释。它不是本页教的文档块形状。方法的 Javadoc 以 /** 开始，以 */ 结束。@param 与 @return 标签放在这个块里面。
若你在方法下方、在其他语句之后放一个普通字符串，那不是方法文档。文档块必须是贴在方法上方的注释。把块紧挨着 add。让 main 别上演假文档戏。main 里的调用仍是普通打印返回的和。
当注释写错、方法体却正确时，javac 仍可能成功，java Yard 仍可能打印 12。所以本页要你把注释和签名一起读，不只看屏幕。屏幕证明算术。注释证明你标出了约定。

与 debugging 打印对照

在 debugging 页，println 回答：当和看起来不对时，你的数字实际是什么。在本页，Javadoc 回答：在读者钻进方法体之前，add 承诺什么。你仍然编译 Yard.java 并运行 java Yard。新记号是方法上方的 /**、@param 与 @return。
debugging 把普通输出当手电筒。Javadoc 把结构化注释当方法门上的标签。当标签与参数和返回值相符时，读者少猜。当标签缺失时，程序仍可运行——文档习惯却仍缺失。
若仍打开着残留的 debugging 文件，你可能看到 x=10、y=2 和一个旧的和。切到 Javadoc 文件，让 main 打印 add(10, 2)，并让方法带着文档块。把命名风格讲座留在本页之外。把键盘输入留在本页之外。

进入命名之前

你可以在 add 上方放 /** */，标注 @param x、@param y、@return，并在 java Yard 之后仍看到 12。对保留的演示编译 Yard.java 并运行 java Yard。注释把约定告诉了读者。下一页是命名，你在那里为所写内容选择清楚的名字。
保留带文档的 add 演示，做成清楚的注释加运行一对。练习文档时把 debugging 文件留在本页之外。把 naming 文件留到那一课再打开。这三条习惯是继续前进前的检查点。当标签与签名相符、屏幕显示 12 时，Javadoc 完成本课任务，你已准备好进入下一主题命名。
再过一遍文件夹：一个公共 Yard、一个带文档的 add、main 里一次打印、无键盘等待、无强制命名规则。对你保持打开的演示再运行一次 javac Yard.java 与 java Yard。若屏幕仍显示 12，且注释仍在 add 上方带着 @param 与 @return，文档形状就扎实了，课程可在下一页进入命名。优先在一个方法上放一块清楚的文档注释，让每次阅读都教同一张地图。