docs: referência da API gerada a partir dos includes

[NullSablex]

Os includes são o único lugar onde a assinatura de uma native e a sua documentação ficam lado a lado, e o build.rs já os mantém em passo com o Rust. A api-reference.md repetia essa informação em tabelas escritas à mão — nome, tipo e uma linha de descrição por native, mantidas em sincronia no braço.

A página passa a ser gerada deles. É o equivalente ao cargo doc, para a superfície Pawn.

O que a página passa a conter

Mesma URL, nada de link quebrado. Quatro partes, todas lidas do include:

• Enumerações — MYSQL_OPT_*, códigos de erro, níveis de log e códigos do ORM, com os valores e o comentário de cada entrada. Os valores estavam digitados à mão; fazem parte do contrato, porque um script compara contra eles, e podiam divergir do include em silêncio.
• Índice por seção.
• Constantes documentadas — sem isso o MYSQL_SYNC não teria lugar na referência.
• Natives e o forward, cada um com assinatura, o nome equivalente no include open.mp, descrição, parâmetros, retorno e exemplos.

O arquivo sai do versionamento e é reconstruído a cada build da documentação: sem cópia versionada, não existe cópia velha. O mkdocs.yml observa include/ e o gerador, então mkdocs serve recarrega quando a fonte muda.

Dois formatos de comentário

• JavaDoc (@param, @return), que é o que estes includes usam.
• pawndoc (<summary>, <param name="">, <returns>, <remarks>), que um projeto encontra em includes de terceiros.

Blocos que misturam os dois também funcionam. Como nada neste repositório usa pawndoc, nada aqui notaria esse suporte quebrando — por isso --selftest cobre seis fixtures: JavaDoc, pawndoc em bloco, pawndoc em ///, pawndoc multilinha, misto e vazio.

O que mudou nos includes

@example num bloco de documentação vira bloco de código na página, e as três natives que aceitam MYSQL_SYNC passam a trazer um:

mysql_query(sql, "SELECT COUNT(*) AS n FROM accounts", MYSQL_SYNC);
new total = cache_get_value_name_int(0, "n");

Isso corrige uma lacuna: quem lia a documentação da native não tinha como descobrir a forma bloqueante, porque o @param callback falava apenas do "". As duas natives de prepared statement, que recusam MYSQL_SYNC, passam a dizer isso explicitamente.

Para que um exemplo possa citar uma native, o build.rs agora reescreve nomes dentro de comentários ao gerar o include no estilo open.mp, do nome mais longo para o mais curto — caso contrário mysql_query_file viraria MySQL_Query_file. O mesmo exemplo lê mysql_query em um arquivo e MySQL_Query no outro.

O MYSQL_SAMP_VERSION ganhou bloco de documentação, trazendo para o include a explicação que só existia na página: o build.rs o carimba a partir do Cargo.toml, e compará-lo no arranque é como um gamemode percebe um include esquecido depois de atualizar.

Apresentação

Constantes e literais (MYSQL_SYNC, MYSQL_OPT_PORT, "") são renderizados como código, para não se confundirem com a prosa ao redor. Os títulos de seção perdem o qualificador entre parênteses usado no include — "Query (non-blocking)" vira "Query" —, já que cada entrada informa por si o que faz.

CI

O workflow de documentação executa --selftest e --check antes do build, então uma native sem bloco de documentação reprova o pull request.

Verificação

• 81 entradas: 79 natives, 1 forward e 1 constante documentada, todas com bloco de documentação; mais os 5 enums com 28 valores
• mkdocs build --strict sem avisos
• 196 testes no alvo i686-unknown-linux-gnu, clippy e rustfmt limpos, verificação de codificação dos arquivos Pawn OK

A entrada do changelog foi para a seção 1.4.0, que ainda não foi lançada.