Documentação do código

Nesta página

Documentação do código

estrutura, estrutura
Formatação
Declaração de tipo

Documentação do código

O Mongoid usa seu próprio sabor de YARD para documentação de código. Observe as convenções descritas neste documento.

estrutura, estrutura

Módulos: todas as definições de classe e módulo devem ser precedidas por um comentário de documentação.
```
# This is the documentation for the class. It's amazing
# what they do with corrugated cardboard these days.
class CardboardBox
```
Métodos: Todas as definições de método devem ser precedidas de um comentário de documentação. Utilize @param, @yield e @return para especificar entradas e saída. Para obter mais detalhes, consulte Declaração de Tipo abaixo.
```
# 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)
```
Erros: Use @raise para explicar erros específicos do método.
```
# @raise [ Errors::Validations ] If validation failed.
def validate!
```
Métodos privados: Os métodos privados devem ser documentados, a menos que sejam tão breves e diretos que seja obvio o que eles fazem. Observe que, por exemplo, um método pode ser breve e direto, mas o tipo de seu parâmetro pode não ser lógico, caso em que o parâmetro deve ser adequadamente documentado.
```
private
# Documentation is optional here.
def do_something_obvious
```
API Privada: classes e métodos públicos que não se destinam ao uso externo devem ser marcados como @api private . Esta macro não requer um comentário.
Observe que, como os módulos do Mongoid são mistos em classes de aplicativos, a visibilidade private de um método não indica necessariamente seu status como um método privado da API.
```
# This is an internal-only method.
#
# @api private
def dont_call_me_from_outside
```
Notas e TODOs: Use @note para explicar advertências, casos extremos e comportamento que podem surpreeender os usuários. Use @todo para registrar acompanhamentos e sugestões para melhorias futuras.
```
# Clear all stored data.
#
# @note This operation deletes data in the database.
# @todo Refactor this method for performance.
def erase_data!
```
Itens obsoletos: use a macro @deprecated para indicar a funcionalidade obsoleta. Esta macro não requer um comentário.
```
# This is how we did things back in the day.
#
# @deprecated
def the_old_way
```

Formatação

Quebra de linha: use o recuo de espaço duplo ao envolver linhas de macros. Não indente quebras de linha na descrição.

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

Espaço em branco: não use linhas de comentário vazias à esquerda/à direita ou mais de uma linha de comentário vazia consecutiva.

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

Declaração de tipo

Uniões de tipo: Use o pipe | para denotar uma união de tipos permitidos.
```
# @param [ Symbol | String ] name Either a Symbol or a String.
```
Tipos aninhados: use colchetes < > para denotar o aninhamento de tipo.
```
# @param [ Array<Symbol> ] array An Array of symbols.
```
Hash: use a vírgula , para denotar os tipos de chave e valor.
```
# @param [ Hash<Symbol, Integer> ] hash A Hash whose keys are Symbols,
#   and whose values are Integers.
```
Array: Use o pipe | para denotar uma união de tipos permitidos.
```
# @param [ Array<Symbol | String> ] array An Array whose members must
#   be either Symbols or Strings.
```
Array: use a vírgula , para denotar os tipos de cada posição em uma tupla.
```
# @return [ Array<Symbol, Integer, Integer> ] A 3-member Array whose first
#   element is a Symbol, and whose second and third elements are Integers.
```
Array: Use o pipe | no nível superior se os tipos internos não puderem ser mistos dentro do Array.
```
# @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 aninhados: para maior clareza, use colchetes [ ] para denotar uniões aninhadas quando vírgulas também forem usadas.
```
# @param [ Hash<Symbol, [ true | false ]> ] hash A Hash whose keys are Symbols,
#   and whose values are boolean values.
```
Valores Ruby: Valores específicos podem ser denotados no tipo usando a sintaxe Ruby.
```
# @param [ :before | :after ] timing One of the Symbol values :before or :after.
```
Verdadeiro, falso e nulo: use true, false e nil em vez de TrueClass, FalseClass e NilClass. Não use Boolean como um tipo, pois ele não existe em Ruby.
```
# 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.
```
Auto de retorno: especifique o valor de retorno self onde um método retorna self.
```
# @return [ self ] Returns the object itself.
```
Splat Args: Use reticências de três pontos ... na declaração de tipo e uma estrela * no nome do parâmetro para denotar um splat.
```
# @param [ String... ] *items The list of items name(s) as Strings.
def buy_groceries(*items)
```

Splat Args: Não use Array como o tipo, a menos que cada arg seja realmente uma 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"])

Splat Args: Use a vírgula , para denotar posicionalidade em um splat.
```
# @param [ Symbol..., Hash ] *args A list of names, followed by a hash
#   as the optional last arg.
def say_hello(*args)
```
Splat Args: especifique uniões de tipo com colchetes [ ].
```
# @param [ [ String | Symbol ]... ] *fields A splat of mixed Symbols and Strings.
```

Argumentos de palavra-chave: seguindo as convenções de YARD, use @param para argumentos de palavra-chave e especifique nomes de argumentos de palavra-chave 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)

Opções de hash: defina as opções de valor-chave do hash com a macro @option imediatamente após o hash @param. Nota Os nomes de parâmetros @option são símbolos.

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

Splats duplos: use asterisco duplo ** no nome do parâmetro para denotar uma palavra-chave arg splat (splat duplo). Observe que o tipo não precisa ser declarado no elemento de preenchimento duplo, pois é implicitamente <Símbolo, Objeto>. Em vez disso, defina os tipos de valor com a macro @option abaixo. Nota Os nomes de parâmetros @option são símbolos.

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

Blocos: Use @yield para especificar quando o método gera um bloco.

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

Blocos: se o método especificar explicitamente um argumento de bloco, especifique o argumento de bloco usando @param precedido por um sinal tipográfico & e também especifique @yield. A observação @yield deve ser usada mesmo quando o método chama block.call em vez 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

Bloqueios: Use @yieldparam e @yieldreturn em vez de @yield quando for benéfico para a clareza.

# @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: Os argumentos Proc devem usar @param (não @yield). As entradas para o proc podem ser especificadas como subtipo(s).

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

Voltar

Contribuindo

Diretivas de contribuição