エンジニアのためのJavadoc再入門講座

第1章　なぜJavadocを使うのか

1.1　プログラムを説明するドキュメントはなぜ必要？
　　1.1.1　ソースコードがドキュメント？
　　1.1.2　「コードを読め！」と言われても・・・・・
　　1.1.3　　仕様を書くにはExcelが必要？
1.2　Javadocを使って仕様を書く
　　1.2.1　Javadocとは何か？
　　1.2.2　ドキュメンテーションコメントには何を書くのか？
　　1.2.3　ドキュメンテーションコメントがもたらすメリット
　　1.2.4　ドキュメンテーションコメントでは書き表せないこと
1.3　よいコメント、悪いコメント
　　1.3.1　コードの翻訳に意味はない
　　1.3.2　ドキュメンテーションコメントを書くのが難しい理由
1.4　わかりやすい仕様を書くためには

第2章　Javadocの基礎

2.1　ドキュメンテーションコメント
　　2.1.1　ドキュメンテーションコメントとして認識されるコメント
　　2.1.2　Javadocタグの存在
　　2.1.3　HTMLとしての記述
2.2　ドキュメンテーションコメントを文章として仕上げる
　　2.2.1　テキストレベルでの整形はやめよう
　　2.2.2　段落のマークアップ
　　2.2.3　箇条書きの実現方法
　　2.2.4　特殊な文字を簡単にエスケープする
　　2.2.5　表を記述する
　　2.2.6　視覚系要素の使い方
2.3　ハイパーリンクの設定方法
　　2.3.1　他のクラスやメソッドに対してリンクを張る
　　2.3.2　メソッドへのリンクの貼り方
　　2.3.3　リンクに表示される文字列を普通のフォントにする
　　2.3.4　静的フィールド値の参照
　　2.3.5　関連項目には＠seeでリンクを設定する

第3章　メソッドやフィールドに対するドキュメンテーションコメントの記述方法

3.1　「メソッド名の日本語訳」はいらない！
3.2　メソッドに対するドキュメンテーションコメントの基本
　　3.2.1　引数に対するドキュメンテーションコメント
　　3.2.2　返却値に対するドキュメンテーションコメント
　　3.2.3　例外に対するドキュメンテーションコメント
3.3　引数／返却値／例外の説明として記述すべきこと
　　3.3.1　引数に対する説明の記述方法
　　3.3.2　返却値に対する説明の記述方法
　　3.3.3　例外に対する説明の記述方法
3.4　メソッドの主説明に記述すべきこと
3.5　フィールドに対するドキュメンテーションコメント
3.6　説明が省略された場合のデフォルトを決定しておく
　　3.6.1　典型的な特異値の省略
　　3.6.2　booleanを返すメソッドではtrueのケースだけを書く
　　3.6.3　setter／getterに対するドキュメンテーションコメントの書き方
3.7　可視性とドキュメントメンテーションコメント
　　3.7.1　privateに対するドキュメンテーションコメントは不要
　　3.7.2　protectedに対しては継承を意識して書く
　　3.7.3　publicに対するドキュメンテーションコメントは責任が重い
3.8　継承とドキュメンテーションコメント
　　3.8.1　メソッドコメントの自動継承
　　3.8.2　継承元のドキュメンテーションコメントを引用する

第4章　クラスに対するドキュメンテーションコメントの記述方法

4.1　クラスに対するドキュメントの存在意義
4.2　インターフェースのドキュメントに求められるもの
4.3　クラスのドキュメントに求められるもの
4.4　継承を意識した記述
　　4.4.1　抽象メソッドにおける実装要求
　　4.4.2　オーバーライド可能なメソッドの自己利用
　　4.4.3　骨格実装の扱い
　　4.4.4　サブクラスでの差分の表現
4.5　特殊なクラス
　　4.5.1　アノテーション
　　4.5.2　列挙型
　　4.5.3　例外

第5章　Javadocのその他の機能

5.1　パッケージに対するドキュメンテーションコメント
5.2　シリアライズ可能なクラスに対するドキュメンテーションコメント
　　5.2.1　シリアライズ対象フィールドを示す＠serialタグ
　　5.2.2　serialPersistentFieldsを利用したシリアライズ対象フィールドの指定
　　5.2.3　シリアライズ／デシリアライズの方法をカスタマイズした場合
　　5.2.4　シリアライズの対象となる情報は別途記載しておく
5.3　クラスやパッケージのバージョン情報
　　5.3.1　作者の示し方
　　5.3.2　現在のバージョンの示し方
　　5.3.3　新しい機能を追加したバージョンの示し方
5.4　ドキュメンテーションコメントにおけるその他の留意点
　　5.4.1　先頭の一文に全力を傾ける
　　5.4.2　使うべきではないものを示す方法
　　5.4.3　リンクを設定する上での注意点

第6章　Javadocを使ってAPI仕様書を生成する

6.1　API仕様書生成の基本
　　6.1.1　ソースコードの格納場所の指定
　　6.1.2　API仕様書生成対象とするパッケージの範囲の指定
　　6.1.3　ソースコード中で使われているクラスの検索場所の指定
　　6.1.4　出力先の指定
　　6.1.5　最終的なコマンドラインイメージ
6.2　MavenやAntを使ってAPI仕様書を生成する
　　6.2.1　MavenによるAPI仕様書の生成
　　6.2.2　AntによるAPI仕様書の生成
6.3　API仕様書の使い方
　　6.3.1　API仕様書の画面構造
　　6.3.2　API仕様書のディレクトリ構造
　　6.3.3　API仕様書に盛り込めないもの
6.4　出力方法のカスタマイズ
　　6.4.1　ドキュメンテーションコメントに出力する可視性の指定
　　6.4.2　クロスリファレンス的な利用
　　6.4.3　バージョンや作者の出力
　　6.4.4　タイトルや著者権情報を埋め込む
　　6.4.5　各種の出力の抑制
6.5　エンコーディングと国際化
　　6.5.1　ソースコードのエンコーディング
　　6.5.2　API仕様書のエンコーディング
　　6.5.3　API仕様書の言語を決める
　　6.5.4　エンコーディング指定のまとめ
6.6　外部のAPI仕様書へとリンクを設定する
　　6.6.1　API仕様書生成時にほかのAPI仕様書を参照する
　　6.6.2　オフラインでもほかのAPI仕様書へのリンクが設定できるようにする
　　6.6.3　2つのAPI仕様書の間で相互参照を生成する
　　6.6.4　Ant／Mavenでの利用例
6.7　ソースファイルへのリンクを生成する
6.8　概要ページのカスタマイズ
　　6.8.1　概要ページにドキュメントを追加する
　　6.8.2　概要ページのパッケージ一覧をグルーピングする
6.9　その他の特筆すべき機能
　　6.9.1　API仕様書で利用するCSSファイルを指定する
　　6.9.2　＠serialタグの利用を確認する
　　6.9.3　索引の分割

第7章　アノテーションによる仕様記述

7.1　再び「契約による設計」
7.2　Contract4J5を使って契約を明確化する
　　7.2.1　Contract4J5とは
　　7.2.2　Groovyによる契約の記述
　　7.2.3　条件を表現するアノテーション
　　7.2.4　Contract4J5の特別なキーワード
7.3　Contract4J5の実例
　　7.3.1　Contract4J5の入手とインストール
　　7.3.2　対象のクラスに＠Contractを付与する
　　7.3.3　事前条件の記述
　　7.3.4　事後条件の記述
　　7.3.5　不変条件の記述
7.4　Contract4J5を使ったプログラムを動かしてみる
　　7.4.1　AspectJのインストール
　　7.4.2　ajcによるコンバイル
　　7.4.3　契約が付与されたクラスの実行例
　　7.4.4　API仕様書の生成
7.5　契約記述の詳細
　　7.5.1　事前条件でオブジェクトの状態をチェックする
　　7.5.2　事後条件でメソッドの結果を検証する
　　7.5.3　キーワード＄oldの制約
　　7.5.4　継承と契約

お問い合わせ

内容についてのお問い合わせは、正誤表、追加情報をご確認後に、お送りいただくようお願いいたします。

正誤表、追加情報に掲載されていない書籍内容へのお問い合わせや
その他書籍に関するお問い合わせは、書籍のお問い合わせフォームからお送りください。

利用許諾に関するお問い合わせ

本書の書影（表紙画像）をご利用になりたい場合は書影許諾申請フォームから申請をお願いいたします。
書影（表紙画像）以外のご利用については、こちらからお問い合わせください。