/ /

ODM para Mongoid en Ruby

Problemas y Ayuda

Docs Home

Librerías de clientes

Ruby

ODM para Mongoid en Ruby

Problemas y Ayuda

Documentación del código

Overview

En esta guía, aprenderá sobre las convenciones de documentación de código de Mongoid. Si tiene alguna sugerencia para mejorar la documentación de la API o introducir una nueva función, puede usar esta guía para formatear su documentación.

Mongoid utiliza una variación de PATIO, una herramienta de documentación de Ruby, para la documentación de su código.

Estructura

Módulos: Todas las definiciones de clases y módulos deben estar precedidas por un comentario de documentación.
```
# This is the documentation for the class. It's amazing
# what they do with corrugated cardboard these days.
class CardboardBox
```
Métodos: Todas las definiciones de métodos deben ir precedidas de un comentario en la documentación. Uso @param, @yield y @return para especificar entradas y salidas. Para obtener más información, consulte la sección Declaración de tipos.
```
# 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)
```
Errores: utilice @raise para describir errores específicos del método.
```
# @raise [ Errors::Validations ] If validation failed.
def validate!
```
Métodos privados: Los métodos privados deben documentarse a menos que sean tan breves y directos que resulte obvio su función. Tenga en cuenta que, por ejemplo, un método puede ser breve y directo, pero el tipo de su parámetro puede no ser obvio; en ese caso, el parámetro debe documentarse adecuadamente.
```
private
# Documentation is optional here.
def do_something_obvious
```
API Privada: Las clases y métodos públicos que no están destinados a uso externo deben marcarse @api private como. Esta macro no requiere comentario.
Tenga en cuenta que, debido a que los módulos de Mongoid están mezclados en clases de aplicación, la visibilidad private de un método no indica necesariamente su estado como método privado de API.
```
# This is an internal-only method.
#
# @api private
def dont_call_me_from_outside
```
Notas y tareas pendientes: Use @note para explicar advertencias, casos extremos y comportamientos que puedan sorprender a los usuarios. Use @todo para registrar seguimientos y sugerencias para futuras mejoras.
```
# Clear all stored data.
#
# @note This operation deletes data in the database.
# @todo Refactor this method for performance.
def erase_data!
```
Obsolescencia: Utilice la @deprecated macro para indicar una funcionalidad obsoleta. Esta macro no requiere comentario.
```
# This is how we did things back in the day.
#
# @deprecated
def the_old_way
```

Formateo

Ajuste de línea: Use sangría de doble espacio al ajustar las líneas de las macros. No aplique sangría al ajustar las líneas en la descripción.

# 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.

Espacio en blanco: no utilice líneas de comentario vacías al principio o al final, ni más de una línea de comentario vacía consecutiva.

# DO THIS:
# @return [ Symbol ] The return value
def my_method
# NOT THIS:
# @return [ Symbol ] The return value
#
def my_method
# NOT THIS:
# @param [ Symbol ] foo The input value
#
#
# @return [ Symbol ] The return value
def my_method(foo)

Declaración de tipo

Uniones de tipos: utilice la barra vertical | para indicar una unión de tipos permitidos.
```
# @param [ Symbol | String ] name Either a Symbol or a String.
```
Tipos anidados: utilice corchetes angulares < > para indicar la anidación de tipos.
```
# @param [ Array<Symbol> ] array An Array of symbols.
```
Hash: utilice , la coma para indicar los tipos de clave y valor.
```
# @param [ Hash<Symbol, Integer> ] hash A Hash whose keys are Symbols,
#   and whose values are Integers.
```
Matriz: utilice la barra vertical | para indicar una unión de tipos permitidos.
```
# @param [ Array<Symbol | String> ] array An Array whose members must
#   be either Symbols or Strings.
```
Matriz: utilice , la coma para indicar los tipos de cada posición en una tupla.
```
# @return [ Array<Symbol, Integer, Integer> ] A 3-member Array whose first
#   element is a Symbol, and whose second and third elements are Integers.
```
Matriz: utilice | la tubería en el nivel superior si los tipos internos no se pueden mezclar dentro de la matriz.
```
# @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.
```
Tipos anidados: para mayor claridad, utilice corchetes [ ] para indicar uniones anidadas cuando también se utilizan comas.
```
# @param [ Hash<Symbol, [ true | false ]> ] hash A Hash whose keys are Symbols,
#   and whose values are boolean values.
```
Valores de Ruby: Se pueden indicar valores específicos en el tipo utilizando la sintaxis de Ruby.
```
# @param [ :before | :after ] timing One of the Symbol values :before or :after.
```
Verdadero, Falso y Nulo: trueUse, false y nil en lugar TrueClass FalseClassde,NilClass y. No use Boolean como tipo, ya que no existe en Ruby.
```
# 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.
```
Argumentos de salpicadura: utilice puntos suspensivos de tres puntos ... en la declaración de tipo y * una estrella en el nombre del parámetro para indicar una salpicadura.
```
# @param [ String... ] *items The list of items' names as Strings.
def buy_groceries(*items)
```

Argumentos de Splat: No utilice Array como tipo a menos que cada argumento sea en realidad una matriz.

# 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"])

Argumentos de salpicadura: use la coma , para indicar la posición en una salpicadura.
```
# @param [ Symbol..., Hash ] *args A list of names, followed by a hash
#   as the optional last arg.
def say_hello(*args)
```
Splat Args: especifica uniones de tipos con [ ] corchetes.
```
# @param [ [ String | Symbol ]... ] *fields A splat of mixed Symbols and Strings.
```

Argumentos de palabras clave: siguiendo las convenciones YARD, utilice @param para los argumentos de palabras clave y especifique los nombres de los argumentos de palabras clave como símbolos.

# @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)

Opciones de hash: Defina las opciones de clave-valor de hash con @option la macro inmediatamente después del @param hash. Nota:@option Los nombres de los parámetros son símbolos.

# @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 = {})

Dobles salpicaduras: Use ** el asterisco en el nombre del parámetro para indicar un argumento de palabra clave "splat" (doble salpicadura). Tenga en cuenta que no es necesario declarar el tipo en el elemento de doble salpicadura, ya que implícitamente es <Símbolo, Objeto>. En su lugar, defina los tipos de valor con la @option macro a continuación. Tenga en cuenta que los nombres de los @option parámetros son símbolos.

# @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)

Bloques: utilice @yield para especificar cuándo el método cede a un bloque.

# @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

Bloques: Si el método especifica explícitamente un argumento de bloque, especifíquelo usando @param precedido por el símbolo & & y especifique @yield también. Nota:@yield debe usarse incluso cuando el método invoca block.call yield internamente en lugar de.

# @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

Bloques: utilice @yieldparam y en @yieldreturn lugar de @yield cuando sea beneficioso para mayor claridad.

# @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

Args Proc: Utiliza @param (no @yield) para argumentos proc. Las entradas para el proc pueden especificarse como subtipos.

# @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

Volver

Problemas y Ayuda

Integración de Ruby on Rails