[Java]ドキュメントとjavadocの使用法_html/css_WEB-ITnose

ドキュメントと正しいデバッグは、どのプログラミング言語にとっても非常に重要です。 Java のようなオブジェクト指向言語では、優れたドキュメントとデバッグ技術が重要な役割を果たします。プログラミングを支援するために、JDK はソース プログラムに挿入できる実装命令を提供するだけでなく、完全で明確なドキュメントを自動的に生成するツール javadoc も提供します。これらのドキュメントの説明は HTML 形式で保存されているため、どのブラウザでも表示できます。ドキュメントにはソース コードは含まれません。

実装手順とドキュメント

実装手順

プログラムの複雑な部分に 2 種類の実装手順を埋め込むことができます:

• 行末に挿入して文書の目的を簡潔に説明するタイプ。このような命令は二重スラッシュ記号 // で始まります。

• 別の説明では、コードの大部分を説明するために使用される開始点と終了点を指定する必要があります。このような記述は、「/」で始まり、「/」記号で終わります。

正しい使用方法

プログラミングのヒント: すでに明確なコードをコメントアウトせず、次の方法に従ってできるだけ明確に記述してください。コード:

• ラッチされたデータの意味を示すために適切な変数名を使用します。
• 大きなタスクをモジュール式のサブタスクに分割します。
• メソッドには、各メソッドの動作を明確に説明する名前を付けます。
• 流暢な英語の文章を生成するために、ローカル変数、メンバー変数、メソッドに適切な名前を付けるようにしてください。

メソッドに名前を付けるのが難しい場合があります。その理由は、メソッドが複数の明確なタスクに分割される必要があるためです。

/*该方法反写一个字符串并且去掉首部的 # 符号，然后把字符串改写成大写字母，再返回新的转化后的字符串*/    public static String chandeString(String s){    //首先，反写字符串    String changedS = " ";    for(int i = s.length() - 1;i >= 0; i--)        changedS += s.charAt(i);    //接下來，去掉首部的加重号    while ((changedS.length() > 0) && (changedS.charAt(0) == '#'))        changedS = changedS.substring(1,changedS.length());    //最後，將其转化成大写字母    changedS = changedS.toUpperCase();    //返回转化后的字符串    return changedS;} 

メソッドはその機能を説明するために正しい注釈を使用していますが、メソッド名changeStringは曖昧すぎます。これは明らかに適切なプログラミング方法ではありません。上記の方法とは異なり、次のコードにはコメントがありませんが、より明確で柔軟性が高くなります。

    public static String reveserseString(String s){String reverseS = " ";for(int i = s.length() - 1;i >= 0; i--)    reverseS += s.charAt(i);return reverseS;}public static String removeLeadingChars(String s,char removeThis){while ((s.length() > 0) && (s.charAt(0) == removeThis))    s = s.substring(1,s.length());return s;} 

コメントが不要になるように、元のメソッドを明確に名前が付けられた 2 つのメソッドに分割しました。さらに、最初の文字 # を削除するメソッドの機能を強化して、任意の最初の文字を削除できるようにすることができます。 String クラスには文字を大文字に変換するメソッドがあるため、それを直接呼び出すことができます。

String s = "# Otto";String convert = removeLeadingChars(s,'#');convert = reverseString(convert);convert = convert.toUpperCase(); 

3 つの文を 1 つの文に結合することもできます。

String s = "# Otto";String convert = reverseString(removeLeadingChars(s,'#')).toUpperCase(); 

Java は、JDK ツール javadoc を使用して、クラスの HTML ドキュメントを生成します。クラスが他の状況で再利用される場合は、javadoc を使用して対応するドキュメントを生成する必要があります。

ドキュメント

Java ではソース コードにドキュメントを追加でき、JDK 開発キットの javadoc ツールを使用してコンパイルとタイプセットを行うことができます。このツールは、次のルールに従ってプログラムのソース コードからタグ付きコメントを抽出し、処理、フォーマット、インデックス付け、および HTML ドキュメントへの相互リンクを行うことができます。

• ドキュメントは、記号 /* * で始まり、記号 */ で終わります。
• ドキュメントの説明には、(タイトル タグに加えて) HTML 書式設定ディレクティブを含めることができます。
• ドキュメントの説明は、参照するクラス名、変数、またはメソッドの直前に表示されます。
• ドキュメントには特別なディレクティブ行を含めることができます。 @author Name: コードの作成者を説明します。 @version Number/Date: バージョン番号とコード完成日を示すために使用されます。 @see class#references: 他のドキュメントへのリンクに使用されます。
• メソッドのドキュメントには、次のディレクティブを含めることもできます。 @return rType: メソッドの戻り値の型を示すために使用されます。 @Exception exType: メソッドによってスローされた例外を示すために使用されます。

Javadoc を使用してドキュメントを作成する

reverseString メソッドとremoveLeadingChars メソッドを作成し、Javadoc を使用してこれらのメソッドをドキュメント化します。以下は、Javadoc アノテーションが埋め込まれた完全なプログラムです。

/**This is a text program to text the methods <code>reverseString</code>and<code>removeLeadingChars<.code>.*@author B G .W*@version 2016/5/29*/public class StringAndComments {    /**    *This method reverses the input string,i.e.the input string is returned character by character in reverse order.    *@return String    */    public static String reverseString(String s) {            /*code as before*/    }    /***This method removes all leading characters from the input string s .The character to be removed is determined by the input parameter <code>removeThis</code>*/    public static String removeLeadingChars(String s,char removeThis){    /*code as before*/}    /***This main method texts <code>removeLeadingChars</code>and<code>reverseString</code> to see if they work correctly.*@see StringAndComments#removeLeadingChars(string,char)*@see StringAndComments#reverseString(String)*/    public static void main(String args[]){    String s = "#Otto";    String uncommented = removeLeadingChars(s,'#');    String upper = reverseString(uncommented).toUpperCase();    if(s.toUpperCase().equals(upper))        System.out.println("String is a palindrome");}} 

javadoc によって生成されたドキュメントの最初の行には、プログラム全体の動作が説明されています。説明には、コード スニペット、作成者名、バージョン番号、日付を指定する HTML タグが含まれています。

両方のメソッドの説明では、これらのメソッドの動作について簡単に説明します。特に、各メソッドには戻り値を記述する @return タグがあります。

最後に main メソッドの説明です。主に前のメソッドをテストするために使用されます。

プログラミングのヒント: 完全なプログラムまたはクラスには適切なドキュメントが含まれている必要があり、少なくとも次のものが必要です。

• 与えられたドキュメントを生成するには、javadoc を使用します。クラス全体がそうします。
• @author タグを介して著者名を示します。
• @version でコードのバージョン番号と日付を示します。
• javadoc を使用して、クラス内の各メソッドの簡潔な説明を生成し、メソッドのすべての入力パラメータの意味と戻り値の型を示します。弱いメソッドの入力パラメータには特別な要件があるため、指摘する必要があります。

javadoc 工具

javadoc 工具是 JDK 的一部分，它用来从 Java 源代码中分析并生成文档说明，他可以生成格式良好、交叉连接、具有索引的 HTML 文档。要使用 javadoc 工具，可以在命令行输入如下代码：

javadoc [options]SourceCodeFile.java

对文件名可以使用通配符。下面是一些可选项。

-private：显示所有类和成员。

-version：包括 @version 标签（缺省忽略）。

-author：包括 @author 标签（缺省忽略）。

javadoc 工具 缺省为每个 Java 源文件生成一个 HTML 文件、类层次文件 overview-tree.html 和索引文件 index.html。

前面我们创建了一个 javadoc 注释的程序。用 javadoc 生成 HTML 文档，然后用浏览器查看。当我们输入命令行：

javadocStringAndComments.java 

为了包括作者和版本信息，我们要加上 -version 和 – author 选项：

javadoc -author -versionStringAndComments.java 

该命令执行后创建一些文件，其中包括 StringsAndComments.html 文件。

这是直接用 Eclipse 里的 javadoc 直接生成的图片。