Xcode 5で利用できる新しいドキュメントコマンドは何ですか?[閉まっている]


186

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

サポートされているコマンドとサポートされていないコマンドを教えてください。
それらの使用法のいずれかがdoxygenと異なりますか?

回答:


419

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

ここに画像の説明を入力してください

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

/** 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スタイル)または\doxygenスタイル)プレフィックスで機能します。(すなわち@b\bつまり両方とも同じことを行います。)
  • コマンドは通常、説明している項目の前にあります。(あなたがプロパティを文書化しようとしている場合、すなわち、コメントの前に来なければならない@propertyテキスト。)彼らは、同じ行に、後で来ることができます/*!</**<//!<///<
  • あなたはにドキュメントを追加することができ、クラス、関数、プロパティ、および変数
  • これらのコマンドはすべて、有効なコマンドであることを示すために濃い緑色のテキストで表示されますが、 @returnsます。
  • ドキュメントへの最新の変更が表示される前に、プロジェクトのビルド(またはXcodeの再起動)が必要になる場合があります。

ドキュメントを参照する場所:

1.コードが完了すると、次の短いテキストが表示されます。

ここに画像の説明を入力してください

これは簡単なテキストを表示します(フォーマットなし)。短いテキストが存在しない場合は、最初の@ブロックまでのすべてのテキストの連結が表示されます。存在しない場合(たとえば、@ returnで始まる)、すべてのテキストを連結して、すべての@コマンドを削除します。

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

ここに画像の説明を入力してください

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

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

4. Doxygenで

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

その他の注意事項

Doxygenの概要とObjective-Cコードの文書化方法については、このページは優れたリソースのようです。

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

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

以下は機能しません:

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

以下はサポートされていません(濃い緑色でも表示されません)。

  • \引用
  • \ docbookonly
  • \ enddocbookonly
  • \ endinternal
  • \ endrtfonly
  • \ endsecreflist
  • \ idlexcept
  • \ mscfile
  • \ refitem
  • \関連する
  • \ rtfonly
  • \ secreflist
  • \ショート
  • \ snippet
  • \目次
  • \ vhdlflow
  • \〜
  • 「」
  • ::
  • \ |

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

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

これらのキーワードの一部を以下に示します。

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

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


4
説明ありがとうございます。うまくいけば、AppleがXcodeのマニュアルにそれをコピーすることを
願い

3
\の代わりに@記号を使用することもできます。
Drewsmits 2013年

8
+1素晴らしいコレクション!クイックヘルプに別のクラスのクイックヘルプへのリンクを追加する方法
セルビン2014年

3
を使用@cして、タイプライターのテキストで次の単語を表示することもできますReturns an @c NSString or @c nil.
マシュー・キロス2014年

7
OptionクリックポップアップにURLを表示する方法を見つけましたか?たとえば、Optionキーを押しながらクリックする-[CADisplayLink addToRunLoop:forMode:]と、説明に他のクラスへの名前付きリンクが含まれます(ただし、Web向けのURLも役立つと思います)。
Zev Eisenberg 14

16

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

/**
        Squares a number.

        - parameter parameterName: number The number to square.

        - returns: The number squared.
    */

@param今はどうですか- parameter

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

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

9

意味のある:

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

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

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


5

Swift 2.0ではほとんどのフォーマットが変更されています(Xcode7ß3以降、ß4でも同様)

の代わりに :param: thing description of thing (Swift 1.2の場合と同様)

それは今です - parameter thing: description of thing

ほとんどのキーワードがの- [keyword]: [description]代わりに置き換えられました:[keyword]: [description]。現在、仕事をしませんキーワードのリストには、含まれabstractdiscussionbriefprepostsaseeavailabilityclassdeprecatedmethodpropertyprotocolrelatedref

弊社のサイトを使用することにより、あなたは弊社のクッキーポリシーおよびプライバシーポリシーを読み、理解したものとみなされます。
Licensed under cc by-sa 3.0 with attribution required.