Documentación de código

Overview

En esta guía, puedes aprender sobre las convenciones de documentación de código de Mongoid. Si tienes una sugerencia para mejorar la documentación de la API o introducir una nueva funcionalidad, puedes usar esta guía para ayudarte a formatear tu documentación.

Mongoid utiliza una variación de YARD, una herramienta de documentación para Ruby, para su documentación de 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 de documentación. Utiliza @param, @yield y @return para especificar las entradas y la salida. Para obtener más información, consulta la sección Declaración de tipo.

  # 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: Usa @raise para describir los errores específicos del método.

  # @raise [ Errors::Validations ] If validation failed.
  def validate!

• Métodos Privados: Los métodos privados deben ser documentados a menos que sean tan breves y sencillos que sea obvio lo que hacen. Tenga en cuenta que, por ejemplo, un método puede ser breve y directo, pero el tipo de su parámetro puede no ser evidente, en cuyo caso el parámetro debe estar adecuadamente documentado.

  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 como @api private. Esta macro no requiere comentario.

  Tenga en cuenta que, debido a que los módulos de Mongoid se integran en las clases de la aplicación, private la visibilidad de un método no necesariamente indica su estado como método privado de la API.

  # This is an internal-only method.
  #
  # @api private
  def dont_call_me_from_outside

• Notas y tareas pendientes: Utilice @note para explicar advertencias, casos límite y comportamientos que puedan sorprender a los usuarios. Usa @todo para registrar el seguimiento 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: Use la macro @deprecated para indicar la obsolescencia de una función. Esta macro no requiere comentario.

  # This is how we did things back in the day.
  #
  # @deprecated
  def the_old_way

Formato

• Ajuste de línea: Usa sangría de doble espacio al dividir líneas de macros. No indente los saltos de línea 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.

• Espacios en blanco: No utilices líneas vacías de comentario 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: Usa el pipe | para denotar una unión de tipos permitidos.

  # @param [ Symbol | String ] name Either a Symbol or a String.

• Tipos anidados: Usa corchetes angulares < > para señalar las anidaciones de tipos.

  # @param [ Array<Symbol> ] array An Array of symbols.

• Hash: Use una 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.

• Array: Utilice el pipe | para denotar una unión de tipos permitidos.

  # @param [ Array<Symbol | String> ] array An Array whose members must
  #   be either Symbols or Strings.

• Arreglo: Usa 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.

• Arreglo: Usar pipe | en el nivel superior si los tipos internos no se pueden mezclar en el Arreglo.

  # @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, usa corchetes [ ] para denotar 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 Ruby: los valores específicos pueden indicarse en el tipo mediante la sintaxis de Ruby.

  # @param [ :before | :after ] timing One of the Symbol values :before or :after.

• Verdadero, falso y nulo: Usar true, false y nil en lugar de TrueClass, FalseClass y NilClass. No utilices Boolean como un 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 dispersión: Utiliza tres puntos ... en la declaración del tipo y un asterisco * en el nombre del parámetro para indicar un argumento de dispersión.

  # @param [ String... ] *items The list of items' names as Strings.
  def buy_groceries(*items)

• Argumentos Splat: No use Array como tipo a menos que cada argumento sea realmente un arreglo.

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

• Args de Splat: Utiliza la coma , para indicar la posicionalidad en un splat.

  # @param [ Symbol..., Hash ] *args A list of names, followed by a hash
  #   as the optional last arg.
  def say_hello(*args)

• Argumentos splat: especifica las uniones de tipos con corchetes [ ].

  # @param [ [ String | Symbol ]... ] *fields A splat of mixed Symbols and Strings.

• Argumentos con palabras clave: Siguiendo las convenciones de YARD, utilice @param para argumentos con palabras clave y especifique los nombres de los argumentos con 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: Define las opciones clave-valor de hash con la macro @option inmediatamente después del Hash @param. Nota que los nombres de los parámetros @option 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 = {})

• Double splats: Utiliza double asterisco ** en el nombre del parámetro para indicar un argumento splat por palabra clave (double splat). Tenga en cuenta que no es necesario declarar el tipo en el elemento double-splat, ya que es implícitamente <Symbol, Object>. En cambio, define los tipos de valores con la macro @option a continuación. Nota: los nombres de los parámetros número @option 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: Utiliza @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, especifique el argumento de bloque utilizando @param precedido por un ampersand &, y también especifique @yield. La nota @yield debe usarse incluso cuando las llamadas al método block.call en lugar de yield internamente.

  # @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: usar @yieldparam y @yieldreturn en 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