480 palavras

Documentando código Ruby com YARD

, em Ruby, Documentação

Nesta página
  1. Instalando
  2. As tags
  3. Gerando a documentação
  4. Por onde começar

Todo código vira legado. Quem escreveu sai do time, a regra de negócio muda, e um dia alguém precisa entender um método sem ter ninguém para perguntar. Muitas vezes esse alguém é você mesmo, seis meses depois.

Documentar não precisa ser um projeto à parte. Um comentário em cima do método, no formato certo, já resolve boa parte. O YARD é a ferramenta mais usada para isso no Ruby: ele lê esses comentários e gera uma documentação navegável em HTML.

Instalando

gem install yard

Num projeto com Bundler, coloque no grupo de desenvolvimento:

bundle add yard --group development

As tags

O YARD lê comentários comuns, com algumas tags começando com @. Uma classe documentada fica assim:

# Uma pessoa cadastrada no sistema.
class Person
  # @return [String] o nome completo
  attr_reader :name

  # @return [Integer] a idade em anos
  attr_reader :age

  # Cria uma pessoa a partir dos dados do formulário.
  #
  # @param name [String] o nome completo
  # @param age [Integer] a idade em anos
  # @return [Person] a pessoa criada
  # @raise [ArgumentError] se a idade for negativa
  # @example
  #   Person.create("Ada Lovelace", 36)
  #   # => #<Person @name="Ada Lovelace", @age=36>
  def self.create(name, age)
    raise ArgumentError, "age must be >= 0" if age.negative?

    new(name, age)
  end

  def initialize(name, age)
    @name = name
    @age = age
  end
end

O que cada tag diz:

  • A primeira linha do comentário é o resumo. É ela que aparece nas listagens, então vale uma frase curta.
  • @param descreve um argumento: nome, tipo entre colchetes e o que ele significa.
  • @return diz o que o método devolve. Nos attr_reader, documenta o próprio atributo.
  • @raise avisa quais erros o método pode levantar, e quando.
  • @example mostra o uso. Costuma ser a parte mais lida da documentação.

Duas outras aparecem bastante:

  • @note é para um aviso que quem usa o método precisa ver, como “não é thread-safe” ou “faz uma requisição HTTP”. Não serve para descrever o que o método faz. Isso é o resumo.
  • @deprecated marca o que vai sair, e de preferência diz o que usar no lugar.

Os tipos aceitam mais de uma opção, como [String, nil], e coleções, como [Array<String>].

Gerando a documentação

yard doc

O comando lê o projeto e gera o HTML na pasta doc/. Para navegar por ela com um servidor local:

yard server

O resultado é parecido com a documentação das gems no RubyDoc:

Documentação gerada pelo YARD

Documentação da classe Person gerada pelo YARD

Por onde começar

Documentar um projeto inteiro de uma vez não funciona. O YARD ajuda a escolher por onde começar:

yard stats --list-undoc

Ele mostra a porcentagem do código que está documentada e lista o que falta. Eu começaria pelas classes que mais gente usa e pelos métodos públicos, que são os que alguém de fora vai chamar. Métodos privados e código óbvio podem esperar.

O resto vem com o hábito: quem cria ou altera um método público documenta junto, no mesmo PR.