Documentação Java com boas práticas de Javadoc

O que esta skill faz

Esta skill ajuda a documentar APIs Java públicas e protegidas com comentários Javadoc consistentes. Ela também orienta o uso de tags, herança de documentação, código inline, blocos de exemplo e notas sobre versões ou alternativas.

Quando usar

• Documentar classes, interfaces e métodos públicos
• Descrever parâmetros, retornos e exceções
• Registrar tipos genéricos com @param
• Indicar APIs depreciadas e suas alternativas
• Adicionar exemplos de código ao Javadoc

Como usar

1. Revise o repositório e identifique tipos e membros sem documentação
2. Escreva uma primeira frase curta que resuma o comportamento
3. Adicione tags apenas para elementos realmente presentes
4. Use {@code} ou blocos preformatados nos exemplos
5. Confira se o Javadoc corresponde à implementação atual

O que revisar antes de instalar

• Javadoc desatualizado pode ser mais prejudicial que documentação ausente
• Membros privados simples não exigem comentários redundantes
• A skill não define uma ferramenta específica para gerar o site de documentação

SKILL.md

---
name: java-docs
description: 'Ensure that Java types are documented with Javadoc comments and follow best practices for documentation.'
---

# Java Documentation (Javadoc) Best Practices

- Public and protected members should be documented with Javadoc comments.
- It is encouraged to document package-private and private members as well, especially if they are complex or not self-explanatory.
- The first sentence of the Javadoc comment is the summary description. It should be a concise overview of what the method does and end with a period.
- Use `@param` for method parameters. The description starts with a lowercase letter and does not end with a period.
- Use `@return` for method return values.
- Use `@throws` or `@exception` to document exceptions thrown by methods.
- Use `@see` for references to other types or members.
- Use `{@inheritDoc}` to inherit documentation from base classes or interfaces.
  - Unless there is major behavior change, in which case you should document the differences.
- Use `@param <T>` for type parameters in generic types or methods.
- Use `{@code}` for inline code snippets.
- Use `<pre>{@code ... }</pre>` for code blocks.
- Use `@since` to indicate when the feature was introduced (e.g., version number).
- Use `@version` to specify the version of the member.
- Use `@author` to specify the author of the code.
- Use `@deprecated` to mark a member as deprecated and provide an alternative.