- 開発技術
JavadocでソースコードからAPI仕様書を作成
- #Java
Javadocとは
【エンジニア募集中】フルリモート可◎、売上/従業員数9年連続UP、平均残業8時間、有給取得率90％、年休124日以上 etc. 詳細はこちらから＞
コメントからAPI仕様書を作成するツールです。
こんな感じのコメントから、
(一部抜粋)
|
1 2 3 4 5 6 7 8 9 |
/** * Javadoc説明用のmain関数の説明。 * Hello World * Hello Alice * と出力。 * * @param args コマンドライン引数. 未使用. */ public static void main(String[] args) { |
こんな感じのAPI仕様書のWebページを生成します。
コメント
クラスやメソッド、フィールドの上部に以下の形式のコメントを記述します。
|
1 2 3 4 5 6 |
/** * クラスやメソッド、フィールドの概要(最初のタグを記述するまでが概要) * * @[tag名] タグの値 */ クラスやメソッド、フィールドの宣言 |
例:
|
1 2 3 4 5 6 |
/** * Javadoc説明用のメインクラスの説明 * * @author 作者を記述 */ public class Example { |
コメントの内容は概要とJavadocタグの2つです。
Javadocタグを記述することで引数や返り値の説明などをWebサイトでうまい具合に表示してくれます。Javadocタグは複数記述することが可能です。
タグ
タグはたくさんありますが、今回使うタグを抜粋して説明します。
|
@author |
@author [名前] |
概要、クラス、パッケージ、インターフェース |
可 |
著者名 |
|
@param |
@param [引数名] [引数の説明] |
メソッドのみ |
可 |
引数の説明 |
|
@return |
@return [返し値の説明] |
メソッドのみ |
不可 |
返し値の説明 |
ドキュメント作成
実際にAPI仕様書を生成してみます。
4つのファイルを用意しました。
下記のように配置しています。doc下にAPI仕様書を生成します。
javadoc
-doc
-src
-example
・Example.java
-hello
・Hello.java
-target
・Target.java
-world
・World.java
・Example.java
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 |
package example; import example.hello.Hello; import example.world.World; import example.target.Target; /** * Javadoc説明用のメインクラスの説明 * * @author 作者を記述 */ public class Example { /** * Javadoc説明用のmain関数の説明。 * Hello World * Hello Alice * と出力。 * * @param args コマンドライン引数. 未使用. */ public static void main(String[] args) { printHelloWorld(); printHelloTarget("Alice"); } /** * Hello World * と出力するメソッド。 * */ private static void printHelloWorld() { System.out.print(Hello.getName() + " " + World.getName() + "\n"); } /** * String型のtargetNameを渡すと * Hello [targetName] * と出力するメソッド。 * * @param targetName Targetクラスのstaticフィールドnameに代入したい値 */ private static void printHelloTarget(String targetName) { Target.setName(targetName); System.out.print(Hello.getName() + " " + Target.getName() + "\n"); } } |
・Hello.java
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 |
package example.hello; /** * Helloクラスの説明 * * @author 作者を記述 */ public class Hello { /** * nameフィールドの説明。 * "Hello"で固定。 * */ private static final String name = "Hello"; /** * Helloクラスのテスト用main関数の説明。 * Hello * と出力。 * * @param args コマンドライン引数. 未使用. */ public static void main(String[] args) { System.out.print(getName()); } /** * nameフィールドのgetter * * @return String型のnameフィールドの値 */ public static String getName() { return name; } } |
・Target.java
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 |
package example.target; /** * Targetクラスの説明 * * @author 作者を記述 */ public class Target { /** * nameフィールドの説明 * */ private static String name; /** * Targetクラスのテスト用main関数の説明。 * Target * と出力。 * * @param args コマンドライン引数. 未使用. */ public static void main(String[] args) { setName("Bob"); System.out.println(getName()); } /** * nameフィールドのsetter * * @param name String型. */ public static void setName(String name) { Target.name = name; } /** * nameフィールドのgetter * * @return String型のnameフィールドの値 */ public static String getName() { if (name == null) { return "No Name"; } return name; } } |
・World.java
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 |
package example.world; /** * Worldクラスの説明 * * @author 作者を記述 */ public class World { /** * nameフィールドの説明。 * "World"で固定。 * */ private static final String name = "World"; /** * Worldクラスのテスト用main関数の説明。 * World * と出力。 * * @param args コマンドライン引数. 未使用. */ public static void main(String[] args) { System.out.println(getName()); } /** * nameフィールドのgetter * * @return String型のnameフィールドの値 */ public static String getName() { return name; } } |
/javadocで下記のコマンドを実行します。
|
1 |
1javadoc -encoding utf-8 -author -private -d doc -sourcepath src -subpackages example |
画像のようなサイトが生成されます。
まとめ
今回はJavadocのよく使う部分だけを抜粋して説明しました。
Javadocができることは他にもたくさんあるので、こういうことがしたいということが結構できると思います。JavadocはJDKに含まれてるのですぐ使えます。
ぜひ試してみてください。
【エンジニア募集中】フルリモートも◎(リモート率85.7％)、平均残業8時間、年休124日以上、有給取得率90％ etc. 詳細はこちらから＞
