This repository was archived by the owner on Sep 20, 2026. It is now read-only.
feat: comentários de documentação (Javadoc e XMLdoc) e #pragma deprecated - #36
Merged
Merged
Conversation
O comentário acima de uma declaração passa a ser interpretado, não apenas repassado como texto cru ao editor. Duas convenções circulam no ecossistema Pawn e ambas precisam render o mesmo resultado: - Javadoc (`@param`, `@return`, `@remarks`/`@note`), com linhas de continuação sob cada tag; - XMLdoc (`<summary>`, `<param name="">`, `<returns>`, `<remarks>`), herdado do C# e usado pelo omp-stdlib, cujas tags alimentam o gerador da wiki do open.mp. `intellisense/docs.rs` detecta a convenção pelo conteúdo e normaliza as duas numa estrutura só, consumida por hover, signature help e completion. No XMLdoc o HTML inline vira Markdown (`<b>` negrito, `<c>` código, `<br />` quebra) e `<library>`, `<seealso>` e as âncoras `<a href="#Func">` são descartados: são metadados do gerador da wiki e, num hover, só ocupariam espaço — um `CreateActor` traz vinte `<seealso>`. Cada parâmetro é casado pelo nome, ignorando o sufixo `[]`, e não pela posição: um comentário pode omitir parâmetros ou listá-los fora de ordem. O signature help mostra a descrição do parâmetro sob o cursor; o completion, apenas o resumo, que é o que cabe na lista; o hover, o bloco inteiro, com os rótulos das seções no idioma resolvido. O trigger `@` do completion, que existia só para inserir o marcador `@DEPRECATED`, passa a oferecer as tags de documentação.
A engine reconhecia um marcador em comentário (`// @DEPRECATED`, inline ou na linha anterior) que era invenção nossa. O Pawn já tem a diretiva para isso, e usá-la evita divergir do compilador. A semântica passa a ser a dele: `#pragma deprecated [mensagem]` marca o *próximo símbolo declarado* e não tem forma inline. O texto que a segue é opcional e, quando presente, é anexado ao aviso PP0007 — normalmente é onde se diz o que usar no lugar, a parte acionável do aviso. A mensagem viaja junto com o flag no novo `Deprecation`, que substitui o `bool` no caminho do parser até o `Symbol`. Cobertura inalterada: `native`, `stock`, `public`, `forward`, `static`, `#define`, variáveis globais e `#include` (PP0008), incluindo o pareamento automático entre `forward` e `public`. BREAKING CHANGE: `@DEPRECATED` em comentário deixa de marcar qualquer coisa. Quem o usava precisa trocar por `#pragma deprecated`.
`init`, `analyze` e `upload-sarif` no mesmo SHA — o desalinhamento entre eles quebra o job de análise. Também: softprops/action-gh-release 3.0.2 → 3.0.3, mkdocs-material 9.7.6 → 9.7.7 (alinhando com o repositório da extensão) e pymdown-extensions 11.0.1 → 11.0.2, com os hashes verificados no PyPI.
Acrescenta ao `lsp.md` a seção sobre as duas convenções reconhecidas, com exemplos, e reescreve a seção de depreciação do `diagnostics.md` para a diretiva. Duas lacunas encontradas de passagem: - `PP0018` existia em `codes.rs` e na documentação da extensão, mas faltava na tabela de diagnósticos daqui; - `i18n.md`, `naming-assistant.md` e `naming-lists.md` existiam sem estar no `nav` do mkdocs, então não apareciam no site publicado.
This was referenced Aug 31, 2026
O lint `doc_markdown` lê "XMLdoc" como identificador de código e exige crases. O CI roda clippy com `-W clippy::pedantic -D warnings`, mais rigoroso que o `cargo clippy` sem flags.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
O que muda
Comentários de documentação interpretados. O comentário acima de uma declaração deixa de ser repassado como texto cru ao editor. Duas convenções são reconhecidas, detectadas pelo próprio conteúdo:
@param,@return,@remarks/@note, com linhas de continuação sob cada tag.<summary>,<param name="">,<returns>,<remarks>, o formato herdado do C# que oomp-stdlibusa.No XMLdoc o HTML inline vira Markdown (
<b>negrito,<c>código,<br />quebra) e<library>,<seealso>e as âncoras<a href="#Func">são descartados — servem ao gerador da wiki do open.mp e, num hover, só ocupariam espaço (umCreateActortraz vinte<seealso>).Cada parâmetro é casado pelo nome, ignorando o sufixo
[], e não pela posição: um comentário pode omitir parâmetros ou listá-los fora de ordem. Hover, signature help e completion consomem a mesma estrutura — o signature help mostra a descrição do parâmetro sob o cursor, e o completion, só o resumo.Depreciação pela diretiva do compilador.
#pragma deprecated [mensagem]substitui o marcador@DEPRECATED, que era invenção nossa. A semântica acompanha a do compilador: marca o próximo símbolo declarado, sem forma inline. A mensagem é opcional e, quando presente, é anexada ao aviso PP0007 — normalmente é onde se diz o que usar no lugar.@DEPRECATEDem comentário deixa de marcar qualquer coisa. Quem o usava precisa trocar por#pragma deprecated.Substitui o #35
Este PR já contém o bump do
codeql-actionpara 4.37.9 nos três passos (init,analyze,upload-sarif), com a mesma SHA que o Dependabot propôs — verificado por diff, idêntico byte a byte. O #35 pode ser fechado.Também inclui
tokio1.53.1,regex1.13.1,serde1.0.229,serde_json1.0.151,futures0.3.34; versão para 1.4.0action-gh-release3.0.3,mkdocs-material9.7.7 (alinhando com o repositório da extensão),pymdown-extensions11.0.2 — hashes verificados no PyPIPP0018faltava na tabela de diagnósticos (existe emcodes.rse na doc da extensão), ei18n.md/naming-assistant.md/naming-lists.mdestavam fora donavdo mkdocs, logo não apareciam no site publicadoVerificação
197 testes passando,
cargo fmtlimpo, zero avisos de clippy. Testado no editor contra os includes do open.mp e do SA-MP.