- Contributing >
- Code Documentation
Code Documentation¶
On this page
Code Documentation¶
Mongoid uses its own flavor of YARD for code documentation. Please note the conventions outlined in this document.
Structure¶
Modules: All class and module definitions should be preceded by a documentation comment.
Methods: All method definitions should be preceded by a documentation comment. Use
@param
,@yield
, and@return
to specify inputs and output. For further details, refer to Type Declaration below.Errors: Use
@raise
to explain errors specific to the method.Private Methods: Private methods should be documented unless they are so brief and straightforward that it is obvious what they do. Note that, for example, a method may be brief and straightforward but the type of its parameter may not be obvious, in which case the parameter must be appropriately documented.
API Private: Classes and public methods which are not intended for external usage should be marked
@api private
. This macro does not require a comment.Note that, because Mongoid’s modules are mixed into application classes,
private
visibility of a method does not necessarily indicate its status as an API private method.Notes and TODOs: Use
@note
to explain caveats, edge cases, and behavior which may surprise users. Use@todo
to record follow-ups and suggestions for future improvement.Deprecation: Use the
@deprecated
macro to indicate deprecated functionality. This macro does not require a comment.
Formatting¶
Line Wrapping: Use double-space indent when wrapping lines of macros. Do not indent line wraps in the description.
Whitespace: Do not use leading/trailing empty comment lines, or more than one consecutive empty comment line.
Type Declaration¶
Type Unions: Use pipe
|
to denote a union of allowed types.Nested Types: Use angle brackets
< >
to denote type nesting.Hash: Use comma
,
to denote the key and value types.Array: Use pipe
|
to denote a union of allowed types.Array: Use comma
,
to denote the types of each position in a tuple.Array: Use pipe
|
on the top level if the inner types cannot be mixed within the Array.Nested Types: For clarity, use square brackets
[ ]
to denote nested unions when commas are also used.Ruby Values: Specific values may be denoted in the type using Ruby syntax.
True, False, and Nil: Use
true
,false
, andnil
rather thanTrueClass
,FalseClass
, andNilClass
. Do not useBoolean
as a type since it does not exist in Ruby.Return Self: Specify return value
self
where a method returnsself
.Splat Args: Use three-dot ellipses
...
in the type declaration and star*
in the parameter name to denote a splat.Splat Args: Do not use
Array
as the type unless each arg is actually an Array.Splat Args: Use comma
,
to denote positionality in a splat.Splat Args: Specify type unions with square brackets
[ ]
.Keyword Arguments: Following YARD conventions, use
@param
for keyword arguments, and specify keyword argument names as symbols.Hash Options: Define hash key-value options with
@option
macro immediately following the Hash@param
. Note@option
parameter names are symbols.Double Splats: Use double-star
**
in the parameter name to denote a keyword arg splat (double splat). Note that type does not need declared on the double-splat element, as it is implicitly <Symbol, Object>. Instead, define value types with@option
macro below. Note@option
parameter names are symbols.Blocks: Use
@yield
to specify when the method yields to a block.Blocks: If the method explicitly specifies a block argument, specify the block argument using
@param
preceded by an ampersand&
, and also specify@yield
. Note@yield
should be used even when method callsblock.call
rather thanyield
internally.Blocks: Use
@yieldparam
and@yieldreturn
instead of@yield
where beneficial for clarity.Proc Args: Proc arguments should use
@param
(not@yield
). The inputs to the proc may be specified as subtype(s).