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.
@paramdescreve um argumento: nome, tipo entre colchetes e o que ele significa.@returndiz o que o método devolve. Nosattr_reader, documenta o próprio atributo.@raiseavisa quais erros o método pode levantar, e quando.@examplemostra 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.@deprecatedmarca 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:


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.