Skip to main content

Code-Documentation

We encourage you to use YARD doc to document Ruby code of this repository, here there are our rules on that.

Method documentation​

We don't enforce you to document all methods with all described tags, but we rely on your experience for whether to follow this guide and how deep your code should be documented.

# <Description>
# @see <name> <description>
# @note <description>
# @todo <description>
# @query <description>
#
# @param param1 [<Type>] <description>
# @param param2 [<Type>] <description>
# @yield [yparam1, yparam2] <description>
# @yieldparam yparam1 [<Type>] <description>
# @yieldparam yparam2 [<Type>] <description>
# @yieldreturn [<Type>] <description>
#
# @example
#
# @raise [<ErrorType>] <description>
# @return [<Type>] <description>
def method(param1, param2)

end

Sections​

Please note that each section is separated by an empty comment (#) and there are no leading or trailing empty comments on the whole documentation part.

Description​

<Description>​

This is the first line of the YARD documentation (so no empty comment at the beginning). This tag requires you to briefly explain what the method is doing, adding all useful details that you need can be useful for another developer that reads this code. You can add references or developer notes with the following tags.

@see​

The @see tag can be useful when you need to reference something that is outside the scope of this method, can be an external URL (@see https://example.org Some website but can also points to another class method (Model#method).

@note​

Any additional note can be added by the developer using the @note tag.

@todo​

If there is something still to do, you can add the @todo tag and add a description of what is missing, but more importantly, why it is missing.

@query​

This is a custom tag that you can use to define if the method will query the database. We require it only for methods that directly query the database or uses ActiveRecord methods to do it.

Parameters​

@param​

If the method accepts parameters, you can document them, with the parameter's type and a brief description of it. Please do NOT document only some of them, this can only cause confusion.

@yield​

If the method accepts a block as a yield, with this tag you can describe yield arguments name and count, but you can also add a description of the yield block.

@yieldparam​

With this tag you can specify the type and describe each yield block parameter. As for @param, please do NOT document only some of them, this can only cause confusion.

@yieldreturn​

It is possible to document the return type of the block.

Example​

@example​

In the @example tag you can add as many examples as you think it's necessary to properly understand the method logic. For syntax, please refer to the documentation linked.

Return​

@raise​

When using this tag, you are documenting method's thrown exception. We require you to also specify in which case the exception can be thrown.

@return​

You can document the return type of the method. A missing @return tag in a valid documentation means that the method will return a nil value.