コードのドキュメント

Overview

このガイドでは、Mongoid のコードドキュメント規則について学習できます。 APIドキュメントを改善して新しい機能を導入したいという提案がある場合は、このガイドを使用してドキュメントの形式に役立ちます。

Mongoid は、コードドキュメントにRubyドキュメントツールである YARD のバリエーションを使用します。

構造体

モジュール: すべてのクラスとモジュール定義の前にはドキュメントコメントを付ける必要があります。
```
# This is the documentation for the class. It's amazing# what they do with corrugated cardboard these days.class CardboardBox
```
メソッド: すべてのメソッド定義の前にはドキュメントコメントを付ける必要があります。入力と出力を指定するには、@param、@yield、@return を使用します。詳細については、「型の宣言」セクションを参照してください。
```
# Turn a person into whatever they'd like to be.## @param [ Person ] person The human to transmogrify.## @return [ Tiger ] The transmogrified result.def transmogrify(person)
```
エラー: @raiseメソッド固有のエラーを説明するには、を使用します。
```
# @raise [ Errors::Validations ] If validation failed.def validate!
```
プライベートメソッド: プライベートメソッドは、非常に簡単で簡単なため、内容が明確にならない限り、ドキュメントに記録する必要があります。例、メソッドは短くて簡単ですが、そのパラメーターの型が明確ではない場合があることに注意してください。その場合はパラメーターを適切にドキュメント化する必要があります。
```
private
# Documentation is optional here.def do_something_obvious
```
APIプライベート: 外部での使用を対象としていないクラスと公開メソッドは@api private でマークする必要があります。このマテリアライズドにはコメントは必要ありません。

Mongoid のモジュールはアプリケーションクラスに混在しているため、メソッドのprivateの可視性は必ずしも API プライベートメソッドとしてのステータスを示すものではないことに注意してください。
```
# This is an internal-only method.## @api privatedef dont_call_me_from_outside
```
メモと TODO: ユーザーを予期させる可能性のある警告、エッジケース、動作を説明するには、 @noteを使用します。将来の改善のために追跡と提案を記録するには、 @todoを使用します。
```
# Clear all stored data.## @note This operation deletes data in the database.# @todo Refactor this method for performance.def erase_data!
```
非推奨:非推奨機能を示すには、 @deprecatedマイクロを使用します。このマテリアライズドにはコメントは必要ありません。
```
# This is how we did things back in the day.## @deprecateddef the_old_way
```

形式

行ラップ: マニュアルの行をラップするときに、ダブルスペースのインデントを使用します。説明に行します。
```
# This is the description of the method. Line wraps in the description# must not be indented.## @return [ Symbol ] For macros, wraps must be double-space indented#   on the second, third (and so on) lines.
```
空白:先頭や末尾の空のコメント行、または複数の連続した空のコメント行は使用しないでください。
```
# DO THIS:# @return [ Symbol ] The return valuedef my_method
# NOT THIS:# @return [ Symbol ] The return value#def my_method
# NOT THIS:# @param [ Symbol ] foo The input value### @return [ Symbol ] The return valuedef my_method(foo)
```

型宣言

型の和集合: 許可された型の和集合を示すには、パイプ|を使用します。
```
# @param [ Symbol | String ] name Either a Symbol or a String.
```
ネストされたタイプ:タイプのネストを示すには、角括弧< >を使用します。
```
# @param [ Array<Symbol> ] array An Array of symbols.
```
ハッシュ:キーと値の型を示すには、カンマ,を使用します。
```
# @param [ Hash<Symbol, Integer> ] hash A Hash whose keys are Symbols,#   and whose values are Integers.
```
配列:許可されたタイプの和集合を示すには、パイプ|を使用します。
```
# @param [ Array<Symbol | String> ] array An Array whose members must#   be either Symbols or Strings.
```
配列:ペア内の各位置のタイプを示すには、カンマ,を使用します。
```
# @return [ Array<Symbol, Integer, Integer> ] A 3-member Array whose first#   element is a Symbol, and whose second and third elements are Integers.
```
配列:内部型を配列内で混在させることができない場合は、最上位でパイプ|を使用します。
```
# @param [ Array<Symbol> | Array<Hash> ] array An Array containing only#   Symbols, or an Array containing only Hashes. The Array may not contain#   a mix of Symbols and Hashes.
```
ネストされたタイプ:わかりやすくするために、カンマも使用される場合は、ネストされた和集合を示すために角括弧[ ]を使用します。
```
# @param [ Hash<Symbol, [ true | false ]> ] hash A Hash whose keys are Symbols,#   and whose values are boolean values.
```
Ruby 値: Ruby 構文を使用して、特定の値を型で表示できます。
```
# @param [ :before | :after ] timing One of the Symbol values :before or :after.
```
true、False、Nil: TrueClass 、 FalseClass 、 NilClassではなく、 true 、 false 、 nilを使用します。 Ruby に存在しないため、 Booleanを型として使用しないでください。
```
# DO THIS:# @param [ true | false | nil ] bool A boolean or nil value.
# NOT THIS:# @param [ TrueClass | FalseClass | NilClass ] bool A boolean or nil value.# @param [ Boolean ] bool A boolean value.
```
自己返却:メソッドがselfを返す戻り値selfを指定します。
```
# @return [ self ] Returns the object itself.
```
SPL 引数: スプラットフォームを表すには、型宣言で 3 ドットの省略記号...を使用し、パラメータ名で*を開始します。
```
# @param [ String... ] *items The list of items' names as Strings.def buy_groceries(*items)
```
SPL 引数:各引数が実際に配列でない限り、型としてArrayを使用しないでください。
```
# DO NOT DO THIS:# @param [ Array<String> ] *items The list of items' names as Strings.def buy_groceries(*items)
buy_groceries("Cheese", "Crackers", "Wine")
# DO THIS:# @param [ Array<String>... ] *arrays One or more arrays containing name parts.def set_people_names(*arrays)
set_people_names(["Harlan", "Sanders"], ["Jane", "K", ""Doe"], ["Jim", "Beam"])
```
スプラットフォーム引数: スプラットフォームで位置を示すには、カンマ,を使用します。
```
# @param [ Symbol..., Hash ] *args A list of names, followed by a hash#   as the optional last arg.def say_hello(*args)
```
Slack 引数:角括弧[ ]で型の和集合を指定します。
```
# @param [ [ String | Symbol ]... ] *fields A splat of mixed Symbols and Strings.
```
キーワード引数: YARD 規則に従い、キーワード引数に@paramを使用し、キーワード引数名をシンボルとして指定します。
```
# @param [ String ] query The search string# @param [ Boolean ] :exact_match Whether to do an exact match# @param [ Integer ] :results_per_page Number of resultsdef search(query, exact_match: false, results_per_page: 10)
```
ハッシュオプション:ハッシュ@paramの直後に続く@optionマイクロを使用して、ハッシュキーと値のオプションを定義します。ただし、 @optionパラメータ名は記号であることに注意してください。
```
# @param opts [ Hash<Symbol, Object> ] The optional hash argument or arguments.# @option opts [ String | Array<String> ] :items The items as Strings to include.# @option opts [ Integer ] :limit An Integer denoting the limit.def buy_groceries(opts = {})
```
double SPL:キーワード引数スプラットフォーム（二doubleスプラットフォーム）を表すには、パラメータ名にdoubleスター ** を使用します。タイプは暗黙的に等価であるため、ダブルスプラットフォーム要素で宣言する必要がないことに注意してください。代わりに、 @optionマイクロを使用して値の型を定義します。ただし、 @optionパラメータ名は記号であることに注意してください。
```
# @param **kwargs The optional keyword argument or arguments.# @option **kwargs [ String | Array<String> ] :items The items as Strings to include.# @option **kwargs [ Integer ] :limit An Integer denoting the limit.def buy_groceries(**kwargs)
```
ブロック:メソッドがブロックを生成するタイミングを指定するには、 @yieldを使用します。
```
# @yield [ Symbol, Symbol, Symbol ] Evaluate the guess of who did the crime.#   Must take the person, location, and weapon used. Must return true or false.def whodunit  yield(:mustard, :ballroom, :candlestick)end
```
ブロック: メソッドでブロック引数が明示的に指定されている場合は、とアンパサンドを使用してブロック引数を指定し、@param &@yieldも指定します。メソッドが内部的に yield ではなく block.call を呼び出す場合でも、@yield は使用する必要があることに注意してください。
```
# @param &block The block.# @yield [ Symbol, Symbol, Symbol ] Evaluate the guess of who did the crime.#   Must take the person, location, and weapon used. Must return true or false.def whodunit(&block)  yield(:scarlet, :library, :rope)end
# @param &block The block.# @yield [ Symbol, Symbol, Symbol ] Evaluate the guess of who did the crime.#   Must take the person, location, and weapon used. Must return true or false.def whodunit(&block)  block.call(:plum, :kitchen, :pipe)end
```
ブロック:わかりやすくするために使用される場合、 @yieldではなく@yieldparamと@yieldreturnを使用します。
```
# @param &block The block.# @yieldparam [ Symbol ] The person.# @yieldparam [ Symbol ] The location.# @yieldparam [ Symbol ] The weapon used.# @yieldreturn [ true | false ] Whether the guess is correct.def whodunit(&block)  yield(:peacock, :conservatory, :wrench)end
```
手順引数: @param@yield手順引数には（ではない）を使用します。プロシージャへの入力はサブタイプとして指定できます。
```
# @param [ Proc<Integer, Integer, Integer> ] my_proc Proc argument which must#   take 3 integers and must return true or false whether the guess is valid.def guess_three(my_proc)  my_proc.call(42, 7, 88)end
```

戻る

問題とヘルプ