web-dev-qa-db-ja.com

Javadocでは、<code>タグに複数形の単数オブジェクトをどのように記述すればよいですか？

Identityという名前のクラスがあります。私のjavadocコメントでは、それを複数形として参照しています。私は2つの解決策を考えることができます：参照を<code>Identities</code>または<code>Identity</code>sに変更します。これらはどちらも正しくないと感じており、もっと良い解決策があるかどうか疑問に思っています。

わかりやすくするための例を次に示します。

/**
  * Returns an <code>IdentityBank</code> of <code>Identity</code>s with the given sex.
  */

または

/**
  * Returns an <code>IdentityBank</code> of <code>Identities</code> with the given sex.
  */
javajavadocgrammar
40
maxbfuer

クラスに {@link} を付けて、「...（s）」スタイルの複数形ラベルを使用します。

/**
  * Returns an {@link IdentityBank} of {@link Identity Identity(s)} with the given sex.
  */

これは次のようにレンダリングされます。

IdentityBank of Identity(s) を指定された性別で返します。

読みやすく、より自然で、あなたが言っていることを明白かつ明確にします。

とにかくクラスには{@link}を使用する必要があります。 <code>スタイルのフォーマットを処理し、andは実際のクラスへのHTMLリンクを提供します。

リンクの「（s）」after、つまり{@link Identity}(s)をコーディングできます。これは、{@link}の完全に従来の使用法を意味しますが、 Wordの途中でフォントが変更されます：

指定された性別の IdentityBank of Identity （s）を返します。

どのIMHOが明快さを低下させ、混乱を引き起こす可能性があります。

28
Bohemian

ここでやりたいことが2つあるようです。適切な文法を使用するだけでなく、クラスのリテラル名を逐語的に使用して、javadocのユーザーがそれらを検索できるようにします。

複数形で作業するときにできることの1つは、「Xインスタンス」というフレーズを使用することです。したがって、あなたの例を使用すると、次のようになります。

/**
 * Returns an <code>IdentityBank</code> of <code>Identity</code> instances with the given sex.
 */

複数の値タイプ（インスタンス自体はありません）を指定する必要がある場合は、「X値」を使用できます。たとえば、「int値のリストを返す」と言うことができます。他の受け入れ可能な名前は、「records」、「notes」、「entries」、「notices」、または@ Marco13が述べたように「objects」です。

すでに使用されている用語を使用していない限り、フレームワーク、システム、またはアプリケーションで既存の芸術用語またはクラス名と衝突する用語の使用は避けてください。たとえば、ファイルシステム内のリテラルファイルを参照している場合を除いて、「ケースファイルのリストを返す」とは言わないでください。これを使用してビジネスルールファイルの概念を参照すると、混乱が生じる可能性があります。この理由で避けることを検討する他の用語は、「データベース」、「テーブル」（データベース内の実際のテーブルまたはそれらの抽象化または表現を参照しない限り）、「ページ」、「フォーム」、「シート」、「ドライバー」です。 、 "ports"、 "windows"、 "lists"、 "heaps"、 "stacks"、 "applications"、 "exceptions"（Throwableでない限り）、 "pins"、および "buss" 。

同様に、合理的な名詞はすべて役に立ちますコードのビジネスルールに適合する場合そして理解できます。次のいずれかを実行できます。

  • MapNodeエントリの象限を返します
  • 従業員ドシエのBalancedTreeを返します
42
Robert Columbia

質問のタイトルを見たとき、私は疑問に思いました。これnotは、5分後に「主に意見に基づく」として閉じられたのでしょうか。しかし、それは重要な質問だと思います。私はこれについてあまりにも多くの苦労をしてきましたが、最終的には異なる（目的、つまりnot意見-ベース！）さまざまなオプションの議論-だからここに私の2セントがあります：

クラス名CustomerとIdentityを例として使用すると、次のようにレンダリングされるさまざまなオプションがあります。

  1. すべて Customer sは Identity s

    別のフォントで「s」を使用すると、読みやすさが低下します。 「アイデンティティ」の間違った複数形は疑わしいです。

  2. すべて Customers 持っている Identities

    これは一見ニースに見えるかもしれません。ただし、重大な欠点があります。ファクトリメソッドを含むクラスのクラス名にsを追加するのが一般的な方法です。たとえば、Customerオブジェクトのファクトリメソッドを含むクラスは、慣例により、Customersと呼ばれます。そして、このようなJavaDoc ...：

    Customers クラスのメソッドを使用して Customers を作成できます

    明らかに紛らわしいです：リンクは、クリックしている名前から期待できるドキュメントにリンクしていませんしていません。

  3. 私が通常適用する解決策（そして、アプローチ2の欠点について話すとき、私はすでに上記でそれを使用しました）：

    すべての Customer オブジェクトには Identity オブジェクトがあります。

    はい、少し不自然に聞こえるかもしれませんが、私はそれを最良のトレードオフと考えています。名前 Identity は読みやすく、クラス名であることは明らかです。クラスの名前がIdentityであることは明白です。

補足：私は通常、名前を{@link ...}として挿入します。これは、Eclipseのオートコンプリートと、結果のJavaDocの参照を大幅に簡素化できるため便利です。少なくとも、クラス名がドキュメントブロックに最初に表示されるときは、{@link ...}を使用することをお勧めします。さらに表示するには、<code>...</code>を使用できます。

7
Marco13

私は通常、 Marco13sの回答 （つまり、「オブジェクト」のような他の複数形の単語を含む{@link …}）の3番目のオプションを好みますが、{@linkplain …}の使用も良い選択肢です。

/**
 * Returns an {@link IdentityBank} of {@linkplain Identity identities} with the given sex.
 */

これは次のようにレンダリングされます。

指定された性別で IdentityBank of identities を返します。

このようにして、IDを処理するsomeクラスがあることがわかります（そして、リンクをたどることでどれを見つけることができます）が、それは明らかです（すべてから小文字のスペルとフォーマット）は、逐語的なIdentityBankとは対照的に、これはクラスの正確な名前ではありません。

（注：この例はこの方法に最適ではない場合がありますが、ポイントと使用法を示しています。）

4
siegi