Documentação de Componentes OO

Crie nova documentação para um componente orientado a objetos ou atualize um arquivo de documentação de componente existente analisando a implementação atual.

Determine o modo primeiro

Escolha o fluxo de trabalho antes de escrever qualquer coisa:

1. Use o modo de atualização quando o usuário fornecer um arquivo Markdown de documentação existente, apontar para um caminho de documentação ou solicitar explicitamente para atualizar ou revisar a documentação existente. Siga references/update-mode.md.
2. Use o modo de criação quando o usuário fornecer um arquivo ou pasta de origem, apontar para um caminho de componente ou solicitar a geração de documentação a partir do código. Siga references/create-mode.md.
3. Se código e um arquivo de documentação existente forem fornecidos, trate o arquivo de documentação existente como o destino de saída e use o código-fonte atual como a fonte da verdade.
4. Se a solicitação for ambígua, infira o modo a partir do tipo de caminho sempre que possível: arquivo de documentação Markdown existente significa modo de atualização; caminho de origem/componente significa modo de criação.

Padrões de documentação

• DOC-001: Siga os níveis de documentação do Modelo C4 (Contexto, Contêineres, Componentes, Código)
• DOC-002: Alinhe-se com o template de documentação de arquitetura de software Arc42
• DOC-003: Cumpra o padrão IEEE 1016 de Descrição de Design de Software
• DOC-004: Use princípios de Documentação Ágil (documentação suficiente que agrega valor)
• DOC-005: Tenha desenvolvedores e mantenedores como público-alvo principal

Orientação de análise compartilhada

• ANA-001: Determine o limite principal do componente e se a entrada representa uma pasta, arquivo ou destino de documentação existente
• ANA-002: Examine arquivos de código-fonte para estruturas de classes, herança, composição e interfaces
• ANA-003: Identifique padrões de design, decisões arquiteturais e pontos de integração
• ANA-004: Documente ou atualize APIs públicas, interfaces, dependências e padrões de uso
• ANA-005: Capture parâmetros de método, valores de retorno, comportamento assíncrono, exceções e preocupações de ciclo de vida
• ANA-006: Avalie características de desempenho, segurança, confiabilidade, manutenibilidade e extensibilidade
• ANA-007: Infira fluxo de dados, padrões de colaboração e relacionamentos com componentes adjacentes
• ANA-008: Mantenha a documentação fundamentada na implementação; evite inventar comportamentos que não são suportados pelo código

Requisitos de saída compartilhados

• Use assets/documentation-template.md como a lista de verificação de seções canônica e estrutura base.
• Mantenha a saída em Markdown com uma hierarquia clara de títulos, tabelas onde úteis, blocos de código para exemplos e diagramas Mermaid quando as relações de arquitetura precisarem ser visualizadas.
• Faça com que os exemplos e as descrições de interface correspondam à implementação atual em vez de placeholders genéricos.
• Inclua apenas informações que possam ser suportadas pelo código, estrutura do projeto, configuração ou suposições claramente declaradas.
• Quando a cobertura do código for incompleta, documente a limitação explicitamente em vez de adivinhar.

Otimizações específicas da linguagem

• LNG-001: C#/.NET - async/await, injeção de dependência, configuração, descarte, padrões de opções
• LNG-002: Java - framework Spring, anotações, tratamento de exceções, empacotamento, injeção de dependência
• LNG-003: TypeScript/JavaScript - módulos, padrões assíncronos, tipos, dependências npm, limites de tempo de execução
• LNG-004: Python - pacotes, ambientes virtuais, dicas de tipo, testes, gerenciamento de dependências

Tratamento de erros

• ERR-001: Se o caminho não existir, explique qual caminho era esperado e se a habilidade precisa de um caminho de origem ou de um arquivo de documentação existente
• ERR-002: Se nenhum arquivo de origem relevante for encontrado, documente a lacuna e sugira os locais prováveis para inspecionar em seguida
• ERR-003: Se o destino da documentação não puder ser inferido da solicitação, declare a ambiguidade e peça o caminho ausente apenas quando a inferência não for possível
• ERR-004: Se o código usar padrões arquiteturais não padrão, documente a abordagem personalizada em vez de forçá-la em um padrão genérico
• ERR-005: Se o acesso à origem for incompleto, continue com as evidências disponíveis e chame claramente quaisquer seções não suportadas

Fluxo de trabalho

1. Determine se a tarefa é no modo de criação ou no modo de atualização.
2. Inspecione a implementação do componente e quaisquer arquivos relacionados necessários para entender sua área de superfície pública e estrutura interna.

…