web-dev-qa-db-ja.com

Xcode 5で利用できる新しいドキュメントコマンドは何ですか？

Xcode 5の新機能 の1つは、独自のコードを特別なコメント構文で文書化する機能です。形式はdoxygenに似ていますが、 これらの機能 のサブセットのみをサポートしているようです。

サポートされているコマンドとサポートされていないコマンド
使用法はdoxygenと異なりますか？

objective-cdocumentationcommentsdoxygenxcode5
185
Senseful

Xcode 5.0.2の時点で見つけたすべてのオプションの例を次に示します

enter image description here

それはこのコードで生成されました：

/** First line text.

 Putting \\n doesn't create a new line.\n One way to create a newline is by making sure nothing is on that line. Not even a single space character!

 @a Italic text @em with @@a or @@em.

 @b Bold text with @@b.

 @p Typewritter font @c with @@p or @@c.

 Backslashes and must be escaped: C:\\foo.

 And so do @@ signs: user@@example.com

 Some more text.
 @brief brief text
 @attention attention text
 @author author text
 @bug bug text
 @copyright copyright text
 @date date text
 @invariant invariant text
 @note note text
 @post post text
 @pre pre text
 @remarks remarks text
 @sa sa text
 @see see text
 @since since text
 @todo todo text
 @version version text
 @warning warning text

 @result result text
 @return return text
 @returns returns text


 @code
// code text
while (someCondition) {
    NSLog(@"Hello");
    doSomething();
}@endcode
 Last line text.

 @param param param text
 @tparam tparam tparam text
 */
- (void)myMethod {}

注：

  • コマンドは、/** block */、/*! block */、または///または//!で始まる必要があります。
  • コマンドは@（ headerdoc style）または\（ doxygen style）プレフィックスで動作します。 （つまり、@bと\bは両方とも同じことをします。）
  • コマンドは通常、説明する項目の前に来ます。 （つまり、プロパティをドキュメント化しようとしている場合、コメントは@propertyテキストの前に来る必要があります。）その後、同じ行で/*!<、/**<、//!<、///<を使用できます。
  • クラス、関数、プロパティ、および変数にドキュメントを追加できます。
  • これらのコマンドはすべて、@returnsを除き、有効なコマンドであることを示すために濃い緑色のテキストで表示されます。
  • ドキュメントの最新の変更が表示される前に、プロジェクトをビルド（またはXcodeを再起動）する必要がある場合があります。

ドキュメントの参照先：

1.コードの完了中に、簡単なテキストが表示されます。

enter image description here

これにより、簡単なテキストが表示されます（書式設定なし）。短いテキストが存在しない場合、最初の@blockまでのすべてのテキストの連結が表示されます。存在しない場合（たとえば、@ returnで始まる）、すべての@コマンドを取り除くすべてのテキストを連結します。

2. Optionキーを押しながら識別子名をクリック：

enter image description here

3.クイックヘルプインスペクターパネル

（最初のスクリーンショットを参照してください。）

4. Doxygenで

Xcode 5のコマンドはDoxygenと互換性があるため、Doxygenをダウンロードして使用してドキュメントファイルを生成できます。

その他の注意事項

Doxygenの一般的な紹介とObjective-Cコードを文書化する方法については、 このページ は良いリソースのようです。

サポートされているいくつかのコマンドの説明：

  • @brief ：説明フィールドの先頭にテキストを挿入し、コード補完中に表示される唯一のテキストです。

以下は機能しません：

  • \n：改行を生成しません。改行を作成する1つの方法は、その行に何もないことを確認することです。単一のスペース文字でさえありません！
  • \example

以下はサポートされていません（それらは濃い緑色で表示されません）：

  • \ cite
  • \ docbookonly
  • \ enddocbookonly
  • \ endinternal
  • \ endrtfonly
  • \ endsecreflist
  • \ idlexcept
  • \ mscfile
  • \ refitem
  • \ relatedalso
  • \ rtfonly
  • \ secreflist
  • \ショート
  • \スニペット
  • \目次
  • \ vhdlflow
  • \〜
  • \ "
  • 。
  • ::
  • \ |

Appleが予約したキーワード：

Appleは、ドキュメントでのみ機能する予約キーワードと思われるものを使用しています。それらは濃い緑色で表示されますが、Appleのように使用できないようです。 Appleの使用例は、AVCaptureOutput.hなどのファイルで見ることができます。

これらのキーワードの一部のリストは次のとおりです。

  • @ abstract、@ availibility、@ class、@ discussion、@ deprecated、@ method、@ property、@ protocol、@ related、@ ref。

せいぜい、キーワードは[説明]フィールドに新しい行を作成します（例：@discussion）。最悪の場合、キーワードとそれに続くテキストはクイックヘルプに表示されません（例：@class）。

416
Senseful

Swift 2. は次の構文を使用します。

/**
        Squares a number.

        - parameter parameterName: number The number to square.

        - returns: The number squared.
    */

@paramが- parameterになったことに注意してください。

ドキュメントに箇条書きを含めることもできます。

/**
        - square(5) = 25
        - square(10) = 100
    */
16
Senseful

意味のある：

ドキュメントの最新の変更が表示される前に、プロジェクトをビルドする必要がある場合があります。

時にはこれで十分ではなかった。通常、Xcodeを閉じてプロジェクトを開いてバックアップすると、これらのケースが改善されます。

また、.hファイルと.mファイルで異なる結果が得られます。ドキュメントコメントがヘッダーファイルにある場合、新しい行を取得できません。

9
weezma2004

Swift 2.0のフォーマットのほとんどが変更されました（Xcode7ß3以降、ß4でも同様）

:param: thing description of thingの代わりに（Swift 1.2にあったように）

現在は- parameter thing: description of thingです

ほとんどのキーワードは、- [keyword]: [description]ではなく:[keyword]: [description]に置き換えられました。現在、機能しないキーワードのリストには、abstract、discussion、brief、pre、post、sa、see、availability、class、deprecated、method、property、protocol、related、ref。

5
mittens