Guia de estilo para referência de API: um único formato para cada entrada

O que é

Uma entrada de referência descreve uma função, um endpoint, um tipo ou uma opção. Um guia de estilo para material de referência é um documento interno curto que define, para todas as entradas, as seções e a ordem delas, a forma da frase de abertura e a redação dos fatos recorrentes. A orientação de referência da Microsoft (citada) lista as seções de um artigo de referência numa ordem fixa: título e descrição, declaração ou sintaxe, parâmetros, valor de retorno, observações, exemplo, requisitos e veja também, com exceções ou códigos de erro quando o elemento puder gerá-los. Cada parâmetro traz o tipo de dado e, quando couber, se é obrigatório ou opcional, e a descrição não deve apenas repetir o nome do elemento. A orientação do Google para comentários de referência de API (citada) observa que só a primeira frase de uma descrição aparece nas seções de resumo e nos índices, de modo que a informação mais importante deve estar nela, e que uma descontinuação precisa dizer o que usar no lugar. O OpenAPI (citado) separa o summary, uma declaração curta do que a operação faz, da description, mais longa.

Por que importa

O material de referência é lido por consulta, não em sequência. Quem aprendeu onde fica o valor de retorno numa entrada espera encontrá-lo no mesmo lugar na seguinte; um agente que extrai parâmetros depende da mesma regularidade. Referências geradas (a partir de docstrings, OpenAPI, comentários de documentação) reproduzem a disciplina que existir na origem, por isso o guia de estilo deve ser aplicado na fonte.

Como aplicar

• Primeira frase: uma declaração completa do que o elemento faz, na terceira pessoa, começando por um verbo ("Retorna o ...", "Cria um ..."), que faça sentido sozinha num índice.
• Parâmetros: nome, tipo, obrigatório ou opcional, valor padrão, intervalo ou formato permitido e o que acontece no limite. Um parâmetro sem valor padrão declarado tem comportamento não documentado.
• Valor de retorno: tipo, significado e os casos de vazio, nulo ou não encontrado.
• Erros: uma linha por condição, no formato "condição: erro lançado ou status retornado"; com link para o formato de erro compartilhado.
• Observações: garantias de ordenação, idempotência, efeitos colaterais, limites de taxa, segurança em threads. Nada que pertença a um tutorial.
• Exemplo: uma chamada mínima e executável, com a saída; sempre que possível, mantenha-o executado no CI.
• Descontinuação: a substituição, a versão desde a qual vale e o plano de remoção, já na primeira frase.
• Terminologia: use o termo preferido do glossário para cada conceito e as mesmas unidades e formatos de data em todo o material.

Armadilhas

Resumos que repetem o nome ("getUser: obtém o usuário"). Descrever a implementação em vez do contrato. Restrições declaradas apenas em texto corrido, que um validador aplica de outra forma. Exemplos que já não executam. Ordens de seções diferentes por autor, justamente o problema que o guia existe para eliminar.