code-documentation

Habilidade de Documentação de Código

Visão Geral

Esta habilidade gera documentação profissional e abrangente para projetos de software, bases de código, bibliotecas e APIs. Ela segue as melhores práticas da indústria de projetos como React, Django, Stripe e Kubernetes para produzir documentação precisa, bem estruturada e útil tanto para novos colaboradores quanto para desenvolvedores experientes.

A saída varia desde READMEs de um único arquivo até guias para desenvolvedores com vários documentos, sempre adequada à complexidade do projeto e às necessidades do usuário.

Capacidades Principais

• Gerar arquivos README.md abrangentes com badges, instruções de instalação, uso e referência de API
• Criar documentação de referência de API a partir da análise do código-fonte
• Produzir documentação de arquitetura e design com diagramas
• Escrever guias de integração e contribuição para desenvolvedores
• Gerar changelogs a partir do histórico de commits ou notas de versão
• Criar documentação inline de código seguindo convenções específicas da linguagem
• Suportar formatos JSDoc, docstrings, GoDoc, Javadoc e Rustdoc
• Adaptar o estilo da documentação ao ecossistema e à linguagem do projeto

Quando Usar Esta Habilidade

Sempre carregue esta habilidade quando:

• O usuário pedir para "documentar", "criar documentação" ou "escrever documentação" para qualquer código
• O usuário solicitar um README, referência de API ou guia para desenvolvedores
• O usuário compartilhar uma base de código ou repositório e quiser documentação gerada
• O usuário pedir para melhorar ou atualizar documentação existente
• O usuário precisar de documentação de arquitetura, incluindo diagramas
• O usuário solicitar um changelog ou guia de migração

Fluxo de Trabalho de Documentação

Fase 1: Análise da Base de Código

Antes de escrever qualquer documentação, entenda completamente a base de código.

Passo 1.1: Descoberta do Projeto

Identifique os fundamentos do projeto:

Campo	Como Determinar
Linguagem(ns)	Verificar extensões de arquivo, package.json, pyproject.toml, go.mod, Cargo.toml, etc.
Framework	Observar dependências para frameworks conhecidos (React, Django, Express, Spring, etc.)
Sistema de Build	Verificar Makefile, CMakeLists.txt, webpack.config.js, build.gradle, etc.
Gerenciador de Pacotes	npm/yarn/pnpm, pip/uv/poetry, cargo, go modules, etc.
Estrutura do Projeto	Mapear a árvore de diretórios para entender a arquitetura
Pontos de Entrada	Encontrar arquivos principais, pontos de entrada CLI, módulos exportados
Documentação Existente	Verificar README, docs/, wiki ou documentação inline existentes

Passo 1.2: Análise da Estrutura do Código

Use ferramentas de sandbox para explorar a base de código:

# Obter estrutura de diretórios
ls /mnt/user-data/uploads/project-dir/

# Ler arquivos-chave
read_file /mnt/user-data/uploads/project-dir/package.json
read_file /mnt/user-data/uploads/project-dir/pyproject.toml

# Pesquisar superfícies de API pública
grep -r "export " /mnt/user-data/uploads/project-dir/src/
grep -r "def " /mnt/user-data/uploads/project-dir/src/ --include="*.py"
grep -r "func " /mnt/user-data/uploads/project-dir/ --include="*.go"

Passo 1.3: Identificar o Escopo da Documentação

Com base na análise, determine qual documentação produzir:

Tamanho do Projeto	Documentação Recomendada
Arquivo único / script	Comentários inline + cabeçalho de uso
Pequena biblioteca	README com referência de API
Projeto médio	README + Documentação de API + exemplos
Projeto grande	README + Arquitetura + API + Contribuição + Changelog

Fase 2: Geração de Documentação

Passo 2.1: Geração de README

Todo projeto precisa de um README. Siga esta estrutura:

# Nome do Projeto

[Descrição do projeto em uma linha — o que faz e por que é importante]

[![Badge](https://raw.githubusercontent.com/bytedance/deer-flow/main/link)](#) [![Badge](https://raw.githubusercontent.com/bytedance/deer-flow/main/link)](#)

## Recursos

- [Recurso principal 1 — breve descrição]
- [Recurso principal 2 — breve descrição]
- [Recurso principal 3 — breve descrição]

## Início Rápido

### Pré-requisitos

- [Pré-requisito 1 com versão exigida]
- [Pré-requisito 2 com versão exigida]

### Instalação

[Comandos de instalação com blocos de código prontos para copiar]

### Uso Básico

[Exemplo mínimo funcional que demonstra a funcionalidade principal]

## Documentação

- [Link para a referência completa da API, se separada]
- [Link para a documentação de arquitetura, se separada]
- [Link para o diretório de exemplos, se aplicável]

## Referência da API

[Referência de API inline para projetos menores OU link para documentação gerada]

## Configuração

[Variáveis de ambiente, arquivos de configuração ou opções de tempo de execução]

## Exemplos

[2-3 exemplos práticos cobrindo casos de uso comuns]

## Desenvolvimento

### Configuração

[Como configurar um ambiente de desenvolvimento]

### Testes

[Como executar testes]

### Build

[Como compilar o projeto]

## Contribuição

[Diretrizes de contribuição ou link para CONTRIBUTING.md]

## Licença

[Informações da Licença]

Passo 2.2: Geração de Referência de API

Para cada superfície de API pública, documente:

Documentação de Função / Método:

### `functionName(param1, param2, options?)`

Breve descrição do que esta função faz.

**Parâmetros:**

| Parâmetro | Tipo | Obrigatório | Padrão | Descrição |
|-----------|------|-------------|---------|-------------|
| `param1` | `string` | Sim | — | Descrição de param1 |
| `param2` | `number` | Sim | — | Descrição de param2 |
| `options` | `Object` | Não | `{}` | Opções de configuração |
| `options.timeout` | `number` | Não | `5000` | Tempo limite em milissegundos |

**Retorna:** `Promise<Result>` — Descrição do valor de retorno

**Lança:**
- `ValidationError` — Quando param1 está vazio
- `TimeoutError` — Quando a operação excede o tempo limite

**Exemplo:**

```javascript
const result = await functionName("hello", 42, { timeout: 10000 });
console.log(result.data);
```

Documentação de Classe:

### `ClassName`

Breve descrição da classe e seu propósito.

**Construtor:**

```javascript
new ClassName(config)
```

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `config.option1` | `string` | Descrição |
| `config.option2` | `boolean` | Descrição |

**Métodos:**

- [`method1()`](#method1) — Breve descrição
- [`method2(param)`](#method2) — Breve descrição

**Propriedades:**

| Propriedade | Tipo | Descrição |
|----------|------|-------------|
| `property1` | `string` | Descrição |
| `property2` | `number` | Somente leitura. Descrição |

Passo 2.3: Documentação de Arquitetura

Para projetos médios a grandes, inclua documentação de arquitetura:

# Visão Geral da Arquitetura

## Diagrama do Sistema

[Inclua um diagrama Mermaid mostrando a arquitetura de alto nível]

```mermaid
graph TD
    A[Cliente] --> B[Gateway de API]
    B --> C[Serviço A]
    B --> D[Serviço B]
    C --> E[(Banco de Dados)]
    D --> E
```

## Visão Geral dos Componentes

### Nome do Componente
- **Propósito**: O que este componente faz
- **Localização**: `src/components/nome/`
- **Dependências**: Do que depende
- **API Pública**: Principais exportações ou interfaces

## Fluxo de Dados

[Descreva como os dados fluem pelo sistema para operações principais]

## Decisões de Design

### Título da Decisão
- **Contexto**: Que situação levou a esta decisão
- **Decisão**: O que foi decidido
- **Justificativa**: Por que esta abordagem foi escolhida
- **Compensações**: O que foi sacrificado

Passo 2.4: Documentação Inline de Código

Gere documentação inline apropriada à linguagem:

Python (Docstrings — estilo Google):

def process_data(input_path: str, options: dict | None = None) -> ProcessResult:
    """Processa dados do caminho de arquivo fornecido.

    Lê o arquivo de entrada, aplica transformações com base nas opções
    fornecidas e retorna um objeto de resultado estruturado.

    Args:
        input_path: Caminho absoluto para o arquivo de dados de entrada.
            Suporta formatos CSV, JSON e Parquet.
        options: Dicionário de configuração opcional.
            - "validate" (bool): Habilita validação da entrada. Padrão é True.
            - "format" (str): Formato de saída ("json" ou "csv"). Padrão é "json".

    Returns:
        Um ProcessResult contendo os dados transformados e metadados.

    Raises:
        FileNotFoundError: Se input_path não existir.
        ValidationError: Se a validação estiver habilitada e os dados estiverem malformados.

    Example:
        >>> result = process_data("/data/input.csv", {"validate": True})
        >>> print(result.row_count)
        1500
    """

TypeScript (JSDoc / TSDoc):

/**
 * Busca dados do usuário na API e os transforma para exibição.
 *
 * @param userId - O identificador único do usuário
 * @param options - Opções de configuração para a operação de busca
 * @param options.includeProfile - Se deve incluir o perfil completo. Padrão é `false`.
 * @param options.cache - Duração do cache em segundos. Defina como `0` para desabilitar.
 * @returns Os dados transformados do usuário prontos para renderização
 * @throws {NotFoundError} Quando o ID do usuário não existe
 * @throws {NetworkError} Quando a API está inacessível
 *
 * @example
 * ```ts
 * const user = await fetchUser("usr_123", { includeProfile: true });
 * console.log(user.displayName);
 * ```
 */

Go (GoDoc):

// ProcessData lê o arquivo de entrada no caminho fornecido, aplica as
// transformações especificadas e retorna o resultado processado.
//
// O caminho de entrada deve ser um caminho absoluto para um arquivo CSV ou JSON.
// Se options for nil, as opções padrão são usadas.
//
// ProcessData retorna um erro se o arquivo não existir ou não puder ser analisado.
func ProcessData(inputPath string, options *ProcessOptions) (*Result, error) {

Fase 3: Garantia de Qualidade

Passo 3.1: Verificação de Completude da Documentação

Verifique se a documentação cobre:

• O que é — Descrição clara do projeto que um novato possa entender
• Por que existe — Problema que resolve e proposta de valor
• Como instalar — Comandos de instalação prontos para copiar
• Como usar — Pelo menos um exemplo mínimo funcional
• Superfície da API — Todas as funções, classes e tipos públicos documentados
• Configuração — Todas as variáveis de ambiente, arquivos de configuração e opções
• Tratamento de erros — Erros comuns e como resolvê-los
• Contribuição — Como configurar o ambiente de desenvolvimento e enviar alterações

Passo 3.2: Padrões de Qualidade

Padrão	Verificação
Precisão	Cada exemplo de código deve realmente funcionar com a API descrita
Completude	Nenhuma superfície de API pública deixada sem documentação
Consistência	Mesma formatação e estrutura em toda a documentação
Atualidade	A documentação corresponde ao código atual, não a uma versão antiga
Acessibilidade	Nenhum jargão sem explicação, siglas definidas no primeiro uso
Exemplos	Cada conceito complexo tem pelo menos um exemplo prático

Passo 3.3: Validação de Referências Cruzadas

Garanta:

• Todos os caminhos de arquivo mencionados existem no projeto
• Todas as funções e classes referenciadas existem no código
• Todos os exemplos de código usam as assinaturas de função corretas
• Os números de versão correspondem à versão real do projeto
• Todos os links (internos e externos) são válidos

Guia de Estilo de Documentação

Princípios de Redação

1. Comece com o "porquê" — Antes de explicar como algo funciona, explique por que existe
2. Divulgação progressiva — Comece simples, adicione complexidade gradualmente
3. Mostre, não conte — Prefira exemplos de código em vez de explicações longas
4. Voz ativa — "A função retorna X" não "X é retornado pela função"
5. Tempo presente — "O servidor inicia na porta 8080" não "O servidor iniciará na porta 8080"
6. Segunda pessoa — "Você pode configurar..." não "Os usuários podem configurar..."

Regras de Formatação

• Use cabeçalhos estilo ATX (#, ##, ###)
• Use blocos de código cercados com especificação de linguagem (```python, ```bash)
• Use tabelas para informações estruturadas (parâmetros, opções, configuração)
• Use notas de advertência para informações importantes, avisos e dicas
• Mantenha o comprimento das linhas legível (quebre o texto em cerca de 80-100 caracteres na fonte)
• Use formatação de código para nomes de função, caminhos de arquivo, nomes de variáveis e comandos CLI

Convenções Específicas por Linguagem

Linguagem	Formato de Documentação	Guia de Estilo
Python	Docstrings estilo Google	PEP 257
TypeScript/JavaScript	TSDoc / JSDoc	Convenções TypeDoc
Go	Comentários GoDoc	Effective Go
Rust	Rustdoc (///)	Diretrizes de API Rust
Java	Javadoc	Guia Javadoc Oracle
C/C++	Doxygen	Manual do Doxygen

Manipulação de Saída

Após a geração:

• Salve os arquivos de documentação em /mnt/user-data/outputs/
• Para documentação com vários arquivos, mantenha a estrutura de diretórios do projeto
• Apresente os arquivos gerados ao usuário usando a ferramenta present_files
• Ofereça-se para iterar em seções específicas ou ajustar o nível de detalhes
• Sugira documentação adicional que possa ser valiosa

Notas

• Sempre analise o código real antes de escrever documentação — nunca adivinhe assinaturas de API ou comportamento
• Quando existir documentação existente, preserve sua estrutura a menos que o usuário peça explicitamente uma reescrita
• Para bases de código grandes, priorize documentar a superfície da API pública e as abstrações principais primeiro
• A documentação deve ser escrita no mesmo idioma da documentação existente do projeto; padrão para inglês se não houver nenhuma
• Ao gerar changelogs, use o formato Keep a Changelog
• Esta habilidade funciona bem em combinação com a habilidade deep-research para documentar integrações ou dependências de terceiros