web-dev-qa-db-ja.com

Javadocの段落区切りとして使用するタグはどれですか?

ベストプラクティスに従って、javadocの段落/長いセクションを分割するのに適したHTMLタグはどれですか?

それは...ですか <p />または<br />?どうして?

43
Tom Tresansky

HTML 3.2の国へようこそ。

Docコメントの作成に関する公式ガイドによると、段落を区切る正しい方法は、段落タグ<P>を使用することです。 ドキュメントコメントの形式 に関するセクションの7番目の箇条書きを見てください。

通常、マークアップにこのような古い時代遅れの手法を使用することは強くお勧めします。ただし、この場合、例外を作成する正当な理由があります。 JavaDocツール(カスタムDocletsで根本的に更新されていない限り)は、古くて粗末で、やや壊れたマークアップを生成します。ブラウザは、その日のクレイジーな古いマークアップと後方互換性があるように構築されているため、そのまま使用するのが理にかなっています。 <P>を使用して段落を区切ると、JavaDocの残りの出力と一致します。

55
Wesley

<p />を使用して段落を含むため、つまり段落は<p>および<p>で囲まれる必要があるため、厳密に言うと</p>は意味をなしません。

ただし、<br>は、改行を示す「下位レベル」タグです。したがって、段落を示す意味的に正しい方法は、<p>を使用することです。

<p>This Foo is used to frobincate a {@link Baz}.</p>
<p>It is quite groovy!</p>

vs.

This Foo is used to frobincate a {@link Baz}.<br>
It is quite groovy!

視覚的に、<p>は行間の空白を増やしますが、<br>は新しい行を開始するだけで、大きな空白は挿入されません。

30
Joachim Sauer

Java 8、単一の開始要素(<p>)動作します。

Javadocは終了要素(</p>)。

5
Jin Kwon