Gabriel Felipe Souza SantosandCursor
de65f3063f
Índices por jornada, convenções, diagramas Mermaid, correções de arquitetura (MainShellFrame, TCP/PluginManager), tutoriais com verificações e troubleshooting; remove redirect pitiupi/docs. Co-authored-by: Cursor <cursoragent@cursor.com>
33 lines
1.4 KiB
Markdown
33 lines
1.4 KiB
Markdown
# Convenções da documentação
|
||
|
||
Índice geral: [docs/README.md](../README.md).
|
||
|
||
## Idioma e tom
|
||
|
||
- Português brasileiro, termos de Redes e Java como no código (`ConnectionManager`, `MulticastSocket`).
|
||
- Parágrafos completos; evitar listas longas quando um texto curto explica melhor.
|
||
|
||
## Blocos teoria × implementação
|
||
|
||
Em capítulos de rede e arquitetura, quando um conceito for central, use mentalmente três camadas:
|
||
|
||
1. **Teoria** — como o protocolo ou padrão funciona em geral (com link para [references/README.md](../references/README.md) se precisar de fonte).
|
||
2. **No Pitiupi** — classes e fluxo reais.
|
||
3. **Limitação** — o que o projeto **não** faz (ex.: sem criptografia, sem ICMP nativo no plugin Ping).
|
||
|
||
Não descreva funcionalidade futura como se já existisse.
|
||
|
||
## Código nos exemplos
|
||
|
||
- Trechos de tutorial são **ilustrativos** quando indicado; o aluno completa o plugin (ver [17_tutorial_ping_aula.md](17_tutorial_ping_aula.md)).
|
||
- APIs citadas devem existir no núcleo atual (`PluginWorkspace`, `createPlugin(ConnectionManager, PluginWorkspace)`).
|
||
|
||
## Diagramas
|
||
|
||
- Preferir [Mermaid](https://github.blog/2014-02-14-render-diagrams-markdown/) em arquivos `.md` (GitHub).
|
||
- Diagramas pequenos, um fluxo por figura.
|
||
|
||
## Manutenção
|
||
|
||
Alterou protocolo, SPI ou boot? Atualize o capítulo numerado correspondente e, se for decisão estável, [decision-register.md](../decision-register.md). Ver [13_guia_desenvolvimento.md](13_guia_desenvolvimento.md).
|