コードのドキュメント
コードのドキュメント
Mongoid は独自のフレーバーの 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 private def 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. # # @deprecated def the_old_way
形式
行ラップ: マニュアルの行をラップするときに、ダブルスペースのインデントを使用します。 説明に行します。
# This is the description of the method. Line wraps in the description # should not be indented. # # @return [ Symbol ] For macros, wraps must be double-space indented # on the second, third, etc. lines. 空白:先頭や末尾の空のコメント行、または複数の連続した空のコメント行は使用しないでください。
# GOOD: # @return [ Symbol ] The return value def my_method # BAD: # @return [ Symbol ] The return value # def my_method # BAD: # @param [ Symbol ] foo The input value # # # @return [ Symbol ] The return value def 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
を型として使用しないでください。# GOOD: # @param [ true | false | nil ] bool A boolean or nil value. # BAD: # @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 name(s) as Strings. def buy_groceries(*items) SPL 引数:各引数が実際に配列でない限り、型として
Array
を使用しないでください。# BAD: # @param [ Array<String> ] *items The list of items name(s) as Strings. def buy_groceries(*items) buy_groceries("Cheese", "Crackers", "Wine") # OK: # @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 results def search(query, exact_match: false, results_per_page: 10) ハッシュ オプション:ハッシュ
@param
の直後に続く@option
マイクロを使用して、ハッシュキーと値のオプションを定義します。 ただし、@option
パラメータ名は記号であることに注意してください。# @param opts [ Hash<Symbol, Object> ] The optional hash argument(s). # @option opts [ String | Array<String> ] :items The items(s) 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(s). # @option **kwargs [ String | Array<String> ] :items The items(s) 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 Proc 引数: Proc 引数には
@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