web-dev-qa-db-ja.com

Swift Documentation Comments

Swiftドキュメンテーションコメントについていくつか質問があります。

  1. とにかくAppleドキュメンテーションが持っている。生成されたドキュメント内の関連メソッド。

  2. 迅速に警告タグはありますか？ Objective-Cでは、@ warningを実行し、生成されるドキュメントで太字の警告を受け取ることができます。ただし、：warning：はSwiftドキュメンテーションコメントでは何もしません。

  3. ドキュメントをApple Documentation.Eclipseなどの他の言語の他のIDEで知っている、HTMLドキュメントを生成できます。 XCodeにはこれがありますか？

iosxcodeswiftxcode6documentation-generation
28
ad121

markup を使用して、プレイグラウンドとコードドキュメントの両方のコメントを記述できます。

  • 豊富な遊び場のドキュメントには、//:または/*: */
  • コードのドキュメントには、///または/** */

例

/// This function returns a *hello* string for a given `subject`.
///
/// - Warning: The returned string is not localized.
///
/// Usage:
///
///     println(hello("Markdown")) // Hello, Markdown!
///
/// - Parameter subject: The subject to be welcomed.
///
/// - Returns: A hello string to the `subject`.
func hello(subject: String) -> String {
    return "Hello, \(subject)!"
}

質問への回答

広告。 1。いいえ。 にはSeeAlsoマークアップタグ がありますが、サードパーティライブラリ内の関連するシンボルにリンクするにはまだ十分ではありません。

広告。 2。はい、 Warningマークアップタグ があります。上記の例を参照してください。

広告。 3。Altough Xcode はドキュメンテーションコメント のXML表現を生成できますが、HTMLファイルを生成できません。そのために jazzy を使用することをお勧めします。

58
akashivskyy

Xcode 7.0ベータ4

表記が変更されました（:param:はもう機能しません...）

/// Creates the string representation of the poo with requested size.
///
/// - warning: Be carefull! Poos can hurt.
/// - parameter size: requested size of the poo
/// - returns: string representation of the poo
func makePoo(size: String) -> String
{
    return "Ouch. This is \(size) poo!"
}

そして、それはこのように見えます：

PopUp with documentation

次のいずれかを使用できます///または/** */

39
stevo.mit

（3）HTMLでドキュメントを生成する（またはドキュメントセットを生成する）ために、そのためにビルドされた jazzy を強くお勧めします。

それがまだWIPであっても、それは本当にうまく機能し、Apple documentationと同様のプレゼンテーションでドキュメントを生成します

3
AliSoftware

Swift code Apple HeaderDocをドロップし、 Markdownスタイル 構文に切り替えました。彼らは CommonMark いくつかのSwift特定のキーワード拡張機能を備えたMarkdownのバリアント。

記号ドキュメント

4つのセクションがあり、そのうちの説明のみが常に含まれています。

  • 説明
  • パラメーター
  • 投げる
  • 戻り値

説明の後、他のセクションの順序は重要ではありません。スローセクションとリターンセクションは1つしか持てません。

/**
 What does this function do?

 Some discussion

 - Parameters:
    - firstParam: Describe the first param
    - secondParam: Describe the second param
 - Returns: true or false
 - Throws: SomeError you might want to catch
 */
func someFunction(firstParam: String, secondParam: String) throws -> Bool {
    return true;
}

または同等のもの

/// What does this function do?
///
/// Some discussion
///
/// - Parameters:
/// - firstParam: Describe the first param
/// - secondParam: Describe the second param
/// - Returns: true or false
/// - Throws: SomeError you might want to catch
func someFunction(firstParam: String, secondParam: String) throws -> Bool {
    return true;
}

enter image description here

ドキュメンテーションコメントが段落以外で始まる場合、その内容はすべてディスカッションに入れられます。

キーワードクイックガイド

おしゃれにしたい場合は、説明のどこにでも含めることができるキーワードの長いリストがあります。

- Attention:- Author:- Authors:- Bug:- Complexity:- Copyright:
- Date:- experiment:- important:- invariant:- Note:- Precondition:
- Postcondition:- Remark:- Requires:- seealso:- Since:- Todo:- Version:
- Warning:など.

ドキュメントプレスを自動生成するには ⌘ command+⌥ option+/ またはEditor -> Structure -> Add Documentation。これらのコマンドは、新しい各行の先頭に///を追加します。また、手動で/**を最初の行として追加し、*/をドキュメントの最後の行に追加できます。

続きを読む here 、 here

2
yoAlex5

ドキュメンテーションコメントには次の表記法を使用してください。

/**
 This method sum two double numbers and returns.

 - parameter number1: First Double Number.
 - parameter number2: Second Double Number.
 - returns: The sum of two double numbers.

 # Notes: #
 1. Parameters must be **double** type
 2. Handle return type because it is optional.

 # Example #
```
 if let sum = self.add(number1: 23, number2: 34) {
  print(sum)
 }
 ```
*/


func add(number1: Double, number2: Double) -> Double? {
    return number1 + number2
}

enter image description here

0
Yogendra Singh