2017-03-06 8 views
2

私はJavadocを使うことを学ぶまで、常にインラインコメントを書きます。今私は、行を効果的に選択して、インラインコメントの代わりにJavadocでその行をどうやって伝えることができるのだろうと思っていました。対象行Javadoc

例:
これは私の無効です:

public void test() { 
    //This is a test sentence 
    String testSentence = "Test"; 
    //This is another test sentence 
    String anotherTestSentence = "Test"; 
} 

他の(より効果的な)方法が存在しない場合、私はそれを行うだろうか。確かに存在する場合

/** 
* @line 2 This is a test sentence 
* @line 3 This is another test sentence 
*/ 
public void test() { 
    String testSentence = "Test"; 
    String anotherTestSentence = "Test"; 
} 

は誰もが知っていますJavadocの代わりにインラインコメントを使うべきですか? @lineが奇妙なことをしたことに気付きましたが、それについて何も見つかりません。

+0

'@line'は標準のjavadocタグではありません。好奇心からちょうどどこに来たのですか? –

+0

私はちょうどそれをタイプインし、ラインをターゲットにして、そのラインは左側に奇妙なマーキングを持っています。 – Jason

答えて

1

(少なくとも標準タグセットではできません)できません。

まず、@lineは(下のタグリストを参照してください)標準のJavadocタグではなく、あなたがそれを使用する場合は、の線に沿って何か見に期待:に関するOracleのドキュメントから、

sourcefile.java:1234: warning - @line is an unknown tag. 

セカンドをコメントの配置(強調鉱山):

ドキュメントのコメントは、クラス、インターフェイス、コンストラクタ、メソッド、またはフィールドの宣言の直前に配置した場合にのみ認識されます。クラスの例、メソッドの例、およびフィールドの例を参照してください。 メソッド本文に配置されたドキュメンテーションコメントは無視されます。

残念ながら、これを行う方法はありません。ライン関連のタグはなく、javadocコメントをメソッド本体に入れる方法はありません。

コメントの完全な構文と同様にサポートされているタグのリストは、特に、Oracle's javadoc documentationでオーバーリストされます。

Java 8 docs for the toolがあまりにもありますが、何が本当に変わっていない、私はちょうど閲覧しやすい7のドキュメントを見つける。)

また、哲学的、Kevin Krumwiede hits the nail on the head

-tagletは右のそれを下回っている)あなたはおそらくあなたが望むならば、あなた自身の@lineタグを作成-tag-tagletコマンドラインオプションhere上のセクションを見ることができると述べているすべて。おそらく@lineとの以前の出会いは、誰かのカスタムタグでした。カスタムタグであるかどうかにかかわらず、コメントをメソッド本体自体に入れることはできません。

...これを行わないという哲学的な理由に加えて、文書内の絶対行番号を参照しないように注意する必要があります(カスタムタグか一般的なものか)これは、ファイルの前に行を追加/削除するとすぐにすべてのドキュメントを破棄するためです。これはドキュメンテーションのメンテナンスの悪夢となります。

0

Javadocとインラインコメントは相互排他的ではありません。 Javadocメソッドは、メソッドのインラインコメントを必要と思うところに追加します。通常、メソッドのjavadoc内の特定の行は参照しません。

1

javadocの行に言及するオプションはありません。この背後にある主な理由は、コードを見ることができないので、javadoc内の行について言えば、コードを見ることができない限り、ドキュメントからは意味をなさない。

このようなラインレベルの参照については、インラインコメントを使用する方がよいでしょう。

4

JavadocはAPIを文書化することを意図しており、実装はではなくです。 Javadocで実装の詳細を指定しないでください。実装を変更する能力が制限されるためです。呼び出し側は、文書化した実装の詳細に依存し始める可能性があります。

Javadocを使用すると、クラスまたはメソッドの適切な使用、特に前提条件、事後条件、副作用、および実行時例外を含む例外など、自己記述的でないものを文書化できます。

関連する問題