Wiki documentation guide - Histórico de revisão

MegaManx3: Criou página com 'Esta página descreve a estrutura e os padrões de formatação que devem ser usados ao adicionar ou editar páginas na wiki. = Nomeação de páginas = Os nomes das páginas devem seguir convenções específicas já estabelecidas: * Páginas de classes: `Classes:NomeDaClasse`. Por exemplo, Classes:Actor. Isso é importante não só para manter a organização, mas também para o template Template:Class (como {{class|Actor}} 2026-02-05T16:45:54Z Criou página com 'Esta página descreve a estrutura e os padrões de formatação que devem ser usados ao adicionar ou editar páginas na wiki. = Nomeação de páginas = Os nomes das páginas devem seguir convenções específicas já estabelecidas: * Páginas de classes: <code>Classes:NomeDaClasse</code>. Por exemplo, Classes:Actor. Isso é importante não só para manter a organização, mas também para o template Template:Class (como <code><nowiki>{{class|Actor}}</nowiki></...' Página nova Esta página descreve a estrutura e os padrões de formatação que devem ser usados ao adicionar ou editar páginas na wiki. = Nomeação de páginas = Os nomes das páginas devem seguir convenções específicas já estabelecidas: * Páginas de classes: <code>Classes:NomeDaClasse</code>. Por exemplo, [[Classes:Actor]]. Isso é importante não só para manter a organização, mas também para o template [[Template:Class]] (como <code><nowiki>{{class|Actor}}</nowiki></code>) funcionar corretamente. :: Se você encontrar uma página de classe que por algum motivo não tenha "Classes:" no nome, fique à vontade para movê-la e adicionar o prefixo (deixe um redirecionamento! essa opção já vem marcada por padrão). * Páginas de structs: <code>Structs:NomeDoStruct</code>. Por exemplo, [[Structs:PlayerInfo]]. Note que essas páginas também estão ligadas a um template: [[Template:Struct]] (como <code><nowiki>{{struct|PlayerInfo}}</nowiki></code>). * Páginas de funções: apenas o nome da função diretamente. Por exemplo, {{function|DamageMobj}}. :: Se a mesma função existir em [[ACS]] e [[ZScript]], por exemplo, acrescente <code>(ZScript)</code> ou <code>(ACS)</code> ao nome da página. Garanta também uma nota no topo de cada uma das páginas. O [[Template:SameNameNote]] costuma ser uma boa escolha. :: O mesmo vale quando há funções com o mesmo nome definidas em classes diferentes. Por exemplo, {{function|DrawTexture}} e {{function|DrawTexture (BaseStatusBar)}}. :: Adicionar (ZScript) ou (ACS) às duas páginas nem sempre é necessário. Muitas vezes uma página já existe, então só a página mais nova precisa desse esclarecimento. = Estrutura da página = == Links dentro da página == Use links o máximo possível. Todas as palavras-chave e termos importantes idealmente devem ter links internos. Lembre-se de usar templates úteis. Por exemplo: * [[Template:Class]] — atalho para linkar páginas de classes. Por exemplo, <code><nowiki>{{class|Actor}}</nowiki></code> vira {{class|Actor}}. * [[Template:Struct]] — atalho para linkar páginas de structs. Por exemplo, <code><nowiki>{{struct|TexMan}}</nowiki></code> vira {{struct|TexMan}}. * [[Template:Property]] — atalho para linkar [[Actor properties]]. Por exemplo, <code><nowiki>{{property|Health}}</nowiki></code> vira {{property|Health}}. * [[Template:Flag]] — atalho para linkar [[Actor flags]]. Por exemplo, <code><nowiki>{{flag|Inventory.UNDROPPABLE}}</nowiki></code> vira {{property|Inventory.UNDROPPABLE}}. * [[Template:Function]] — atalho para linkar páginas de funções que também deixa o texto do link em fonte monoespaçada. Por exemplo, <code><nowiki>{{function|A_FireBullets}}</nowiki></code> vira {{function|A_FireBullets}}. : <u>Sempre adicione o prefixo da classe — eles não são opcionais em [[ZScript]]!</u> O prefixo de classe idealmente deve ser escrito em PascalCase. O template funciona sem problemas para isso. * Não deixe de incluir uma seção '''See also''' no final da página, linkando todas as páginas que pareçam relevantes ou tematicamente relacionadas à atual. * Evite copiar e colar grandes trechos do texto em múltiplas páginas; quando precisar disso, é melhor criar um template de inclusão. Temos vários templates de inclusão [https://zdoom.org/wiki/Category:Include_templates '''aqui'''] para conferir. == Páginas de classes e structs == Os nomes de páginas de classes e structs devem começar com "Classes:" e "Structs:" respectivamente, como [[Classes:Actor]] ou [[Structs:StringTable]]. A estrutura geral para qualquer uma das duas deve se parecer com isto: Descrição geral da classe/struct e seu propósito. == Campos == ''Uma lista de campos dessa classe em forma de lista com marcadores, com descrições'' == Métodos == === Virtuais === ''Uma lista com marcadores de funções virtuais definidas nessa classe/struct'' === Estáticos === ''Uma lista com marcadores de funções estáticas definidas nessa classe/struct'' === Não-estáticos === ''Uma lista com marcadores de funções não-estáticas (dinâmicas) definidas nessa classe/struct'' <nowiki>== Definição em [[ZScript]]</nowiki> <nowiki>==</nowiki> <nowiki>{{ZScriptDefinitionNote|<caminho para o código no Github>}}</nowiki> ''Este template insere um aviso de que esse código é apenas referência e adiciona um link para onde o código está no Github. Note que você não precisa de um link completo; em vez disso, seu link deve começar com o que vem depois de <code>zscript/</code> no link, e tudo antes dele (especificamente, <code>https://github.com/ZDoom/gzdoom/blob/master/wadsrc/static/zscript</code>) deve ser removido.'' <nowiki><syntaxhighlight lang="csharp"></nowiki> ''Copie e cole a definição da classe a partir do Github do GZDoom, a menos que seja longa demais. Isso é especialmente relevante para vários atores do jogo que têm seus próprios comportamentos peculiares. Sempre use o bloco <nowiki><syntaxhighlight lang="csharp"> para isso.</nowiki>'' <nowiki></syntaxhighlight></nowiki> <nowiki>== Definição em [[DECORATE]]</nowiki> <nowiki>==</nowiki> <nowiki>{{DecorateDefinitionNote}}</nowiki> ''A definição em DECORATE entra aqui SOMENTE se ela já tiver sido adicionada à página anteriormente. Como DECORATE não é mais usado, novas definições em DECORATE não devem ser adicionadas.'' == Exemplos == ''Um trecho de código de exemplo demonstrando como essa classe/struct pode ser usada. Se você não conseguir adicionar um exemplo agora, coloque '''<nowiki>{{noexamples}}</nowiki>''' aqui.'' == See also == ''Uma lista com marcadores de links para outras páginas relevantes/conectadas, se houver.'' ''Uma lista de categorias relevantes no final:'' <nowiki>[[Category:ZScript]]</nowiki> Páginas de exemplo: * [[Classes:PSprite]] * [[Structs:TexMan]] Templates úteis: * [[Template:ZScriptDefinitionNote]] * [[Template:DecorateDefinitionNote]] == Páginas de funções == A estrutura geral de uma página de função é assim: <nowiki>'''</nowiki><nowiki>{{class|NomeDaClassePai}}</nowiki><nowiki>'''</nowiki> <nowiki>{{c|palavra-chave tipo '''NomeDaFuncao'''(tipoarg ''nomearg'' {{=}} valorpadrao)}}</nowiki> <nowiki>== Uso ==</nowiki> ''Descrição geral de como essa função é usada.'' === Parâmetros === ''Uma lista com marcadores dos argumentos usados pela função, se houver. Exemplo:'' <nowiki></nowiki><nowiki>{{c|tipoarg '''nomearg'''}}</nowiki> <nowiki>:</nowiki>Descrição do argumento. <nowiki>=== Retornos ===</nowiki> ''Descrição dos valores retornados pela função. Se houver mais de um, use uma lista com marcadores.'' == Exemplos == ''Um trecho de código de exemplo demonstrando como essa função pode ser usada. Se você não conseguir adicionar um exemplo agora, coloque '''<nowiki>{{noexamples}}</nowiki>''' aqui.'' <nowiki>== Definição em [[ZScript]]</nowiki> <nowiki>==</nowiki> <nowiki>{{ZScriptDefinitionNote|<caminho para o código no Github>}}</nowiki> ''Este template insere um aviso de que esse código é apenas referência e adiciona um link para onde o código está no Github. Note que você não precisa de um link completo; em vez disso, seu link deve começar com o que vem depois de <code>zscript/</code> no link, e tudo antes dele (especificamente, <code>https://github.com/ZDoom/gzdoom/blob/master/wadsrc/static/zscript</code>) deve ser removido.'' <nowiki><syntaxhighlight lang="csharp"></nowiki> ''Copie e cole a definição da classe a partir do Github do GZDoom, a menos que seja longa demais. Isso é especialmente relevante para vários atores do jogo que têm seus próprios comportamentos peculiares. Sempre use o bloco <nowiki><syntaxhighlight lang="csharp"> para isso.</nowiki>'' <nowiki></syntaxhighlight></nowiki> == See also == ''Uma lista com marcadores de links para outras páginas relevantes/conectadas, se houver.'' ''Uma lista de categorias relevantes no final:'' <nowiki>[[Category:ZScript]]</nowiki> Páginas de exemplo: [[Use]] * [[A_FireBullets]] Templates úteis: * [[Template:ZScriptDefinitionNote]] == Formatação de funções == === No topo da página === Retornos e modificadores de acesso, como private, protected, native, não precisam de formatação especial. O nome da função deve estar em negrito. Nomes dos argumentos devem estar em itálico. '''Valores padrão dos argumentos sempre devem ser fornecidos!''' Exemplo: <nowiki>{{c|virtual void '''SomeMissileFunction'''(Actor ''missile'', double ''angle'' {{=}} 0)}}</nowiki> Resultado: {{c|virtual void '''SomeMissileFunction'''(Actor ''missile'', double ''angle'' {{=}} 0)}} Nota: usar a formatação monoespaçada <code><nowiki>{{c| }}</nowiki></code> para a assinatura inteira é preferível, mas parece falhar em funções que têm o sinal de igual (<code>=</code>) nelas. Para resolver isso, use o template <code><nowiki>{{=}}</nowiki></code> no lugar do sinal de igual. Se a função for definida em uma classe específica, o nome da classe deve ser fornecido no topo da função em negrito, com link para a classe pai. Por exemplo: '''[[Classes:Actor|Actor]]''' {{c|virtual int '''DamageMobj'''(Actor ''inflictor'', Actor ''source'', int ''damage'', Name ''mod'', int flags {{=}} 0, double angle {{=}} 0)}} === No texto === Use o template <nowiki>{{function}}</nowiki> para linkar e destacar funções ou <nowiki>{{c| }}</nowiki> para destacar sem linkar. Use <nowiki><code></code></nowiki> para destacar operadores, modificadores de acesso, etc. Exemplo: <nowiki>{{c|MyFunction}}</nowiki>, <nowiki><code>if</code></nowiki>, <nowiki><code>private</code></nowiki> Resultado: {{c|MyFunction}}, <code>if</code>, <code>private</code> Ao linkar uma função, colocá-la em negrito também pode ser uma boa ideia: <nowiki>'''</nowiki><nowiki>{{function|Tick}}</nowiki><nowiki>'''</nowiki>. Resultado: '''{{function|Tick}}''' == Argumentos de funções == Ao descrever argumentos de funções, as regras de formatação recomendadas são: * Use uma lista com marcadores, com um item novo para cada argumento (listas com marcadores começam com <code></code>) O tipo e o nome do argumento devem ser fornecidos. O nome deve estar em negrito. * O argumento inteiro (tipo e nome) deve estar em monoespaçado via <nowiki>{{c| }}</nowiki> * A descrição do argumento, na maioria dos casos, deve ficar em uma linha separada começando com <code>:</code> Exemplo: <nowiki>{{c|Actor '''missile'''}}</nowiki> <nowiki>:</nowiki>O tipo de ator a ser usado como projétil. <nowiki></nowiki><nowiki>{{c|double '''angle'''}}</nowiki> <nowiki>:</nowiki>O deslocamento relativo ao ângulo do atirador para disparar o projétil. Resultado: * {{c|Actor '''missile'''}} : O tipo de ator a ser usado como projétil. * {{c|double '''angle'''}} : O deslocamento relativo ao ângulo do atirador para disparar o projétil. = Listas com marcadores = Listas com marcadores podem ser criadas com <code></code>. Descrições devem ficar em uma linha separada, começando com <code>:</code>. Item :Descrição do item. Resultado: * Item : Descrição do item. Ao usar listas com marcadores para descrever argumentos de uma função, é preferível que a linha inteira use <code><nowiki>{{c| }}</nowiki></code> para fonte monoespaçada, e o nome do campo em negrito, assim: <nowiki>{{c|tipo '''nomeDoCampo'''}}</nowiki> <nowiki>:</nowiki>Descrição de um campo. Por exemplo: {{c|Vector2 '''position'''}} : Determina a posição do elemento. = Formatação de código = Esta seção cobre como o código usado em exemplos deve ser formatado. Ela pode não ser totalmente abrangente e às vezes será preciso usar bom senso, mas tenta cobrir o máximo possível. Essas diretrizes devem ser seguidas o máximo possível para manter consistência. Como a formatação de ZScript é fortemente enraizada em C/C++, ela herda várias convenções dessas linguagens, mas não todas. C# é um equivalente próximo de ZScript, já que também é uma linguagem gerenciada baseada na sintaxe de C/C++. == Realce == Use <code><nowiki><syntaxhighlight lang="csharp"></nowiki></code> para iniciar um bloco de código e <code><nowiki></syntaxhighlight></nowiki></code> para fechar. '''Evite usar o estilo antigo de formatação de código com espaços no começo das linhas.''' Apesar de permitir combinar código com links e destaques de cor, esse estilo antigo geralmente é bem menos conveniente. Se o código usa referências a outras classes e funções que o usuário talvez não entenda, é melhor adicionar uma nota com uma lista de links relevantes. <nowiki><syntaxhighlight lang="csharp"></nowiki> Código aqui. <nowiki></syntaxhighlight></nowiki> Exemplo:<syntaxhighlight lang="csharp"> // Este é um código de teste. void DoThing() { int x = 5; double y = 2.0; } </syntaxhighlight>Note que essa formatação não suporta links wiki no estilo {{c|<nowiki>[[]]</nowiki>}}. Se por algum motivo você ''precisar'' usar o estilo antigo (por exemplo, está editando uma página antiga que já tem muito disso, ou quer criar código que ''tenha'' links), lembre-se dos templates: * [[Template:Comment]] — deixa a string verde-escura, em itálico e adiciona <code>//</code> antes dela. : Exemplo: <code><nowiki>{{comment|Isto é um comentário}}</nowiki></code> vira {{comment|Isto é um comentário}}. * [[Template:LanguageCodeNote]] — deve ser usado praticamente em qualquer lugar onde uma string visível ao jogador seja escrita explicitamente no código. : É considerada má prática escrever strings voltadas ao jogador, como as de {{property|Inventory.PickupMessage}}, diretamente no código; o ideal é armazená-las no lump [[LANGUAGE]]. Porém, é considerado ''ok'' escrever strings explícitas como exemplo. Então, adicione esta nota nesses exemplos. : Uso: <code><nowiki>{{LanguageCodeNote}}</nowiki></code> vira {{LanguageCodeNote}}. == Sintaxe == {{note|Esta seção trata da sintaxe para trechos de código de exemplo. Trechos do código-fonte do GZDoom devem ser colados como estão e mantidos do jeito que aparecem no GitHub do GZDoom.}} === Formatação === * Use 4 espaços para indentação. * Use estilo Allman para chaves: <syntaxhighlight lang="csharp"> if (expr) { // Código. } </syntaxhighlight> * Sempre inclua chaves: <syntaxhighlight lang="csharp"> // Errado: if (expr) DoThing(); // Errado: if (expr) DoThing(); // Certo: if (expr) { DoThing(); } </syntaxhighlight> * Palavras-chave como <code>if</code>, <code>while</code>, <code>is</code> etc. devem estar sempre em minúsculas. * Use gramática correta em comentários, incluindo pontuação. * Comentários devem ter um espaço após o início e, se forem em bloco, antes do fim: <syntaxhighlight lang="csharp"> // Comentário de linha correto. /* Comentário de bloco correto. / </syntaxhighlight> Não inclua comentário a menos que ele esclareça algum aspecto particularmente confuso do exemplo (e, nesse caso, talvez escolher um exemplo melhor seja a melhor solução). Comentários servem para explicar por que algo está assim, não o que deveria ser autoevidente com bons nomes e formatação. * Formatação de loops: <syntaxhighlight lang="csharp"> for (int i = 0; i < cap; i++) { } while (expr) { } do { } while (expr); </syntaxhighlight> * Formatação de branches: <syntaxhighlight lang="csharp"> if (expr) { } else if (otherExpr) { } else { } </syntaxhighlight> * Switch deve sempre ter <code>break</code> ao fim de cada case, a menos que se espere fall-through: <syntaxhighlight lang="csharp"> switch (val) { case 0: DoThing(); break; default: DoDefaultThing(); break; } </syntaxhighlight> === Campos e variáveis === * Nomes de variáveis e campos devem ser curtos, descritivos e representar com precisão o que significam. * Variáveis locais e propriedades não-Actor devem sempre usar camelCase (ex.: <code>myVar</code>). * Propriedades de Actor devem sempre usar PascalCase (ex.: <code>MyProperty</code>). * Constantes e valores de enum devem sempre usar snake_case em maiúsculas (ex.: <code>MY_CONSTANT</code>). * Valores de enum devem usar um prefixo para indicar a qual enum pertencem (ex.: <code>PREF_ENUM_VALUE</code>). * Se uma variável/campo se refere a um enum específico, use o tipo do enum quando possível em vez de um tipo genérico: <syntaxhighlight lang="csharp"> enum EMyFlags { // ... } int flags; // Não faça isso. EMyFlags flags; // Faça isso. </syntaxhighlight> * Ao atribuir valores, use tipos corretos: <syntaxhighlight lang="csharp"> uint w = 5u; int x = 5; double y = 5.0; bool z = true; String s = "Isto é uma string."; Name n = 'Isto é um name.'; </syntaxhighlight> === Constantes e enums === * Constantes devem declarar o tipo correto para evitar confusão em matemática: <syntaxhighlight lang="csharp"> const HEALTH_THRESHOLD = 50; // int porque health é rastreado assim. const DAMAGE_RANGE = 256.0; // float/double porque ranges usam ponto flutuante. </syntaxhighlight> * Em enums, usar ponto-e-vírgula e vírgula final fica a critério de quem escreve: <syntaxhighlight lang="csharp"> enum EMyEnum { ME_VALUE1, ME_VALUE2, ME_VALUE3, // Vírgula opcional. }; // Ponto-e-vírgula opcional. </syntaxhighlight> * Se o enum usar um tipo específico, espaçamento correto: <syntaxhighlight lang="csharp"> enum EMyEnum : uint </syntaxhighlight> * Só defina valores explicitamente quando o padrão não for suficiente. * Para enums de flags, sempre inclua um valor padrão 0 e use bitshift em vez de potências de 2 “na mão”. É ok definir todos explicitamente: <syntaxhighlight lang="csharp"> enum EMyFlags { MF_NONE = 0, MF_FLAG1 = 1, MF_FLAG2 = 1<<1, MF_FLAG3 = 1<<2 } </syntaxhighlight> === Funções === * Nomes de função devem ser curtos, descritivos e indicar com precisão o que fazem. Use sempre PascalCase. * É altamente preferível que funções <code>action</code> tenham prefixo <code>A_</code>: <syntaxhighlight lang="csharp"> action void A_MyFunction() {} </syntaxhighlight> * Funções que verificam critérios devem ser formuladas como pergunta: <syntaxhighlight lang="csharp"> bool IsOpen() { /* ... / } bool CanUse() { / ... / } </syntaxhighlight> Funções que executam tarefas devem conter um verbo: <syntaxhighlight lang="csharp"> void OpenDoor() { } void UseItem() { } </syntaxhighlight> * Funções anônimas devem ser declaradas assim: <syntaxhighlight lang="csharp"> SPRT A 5 { // Código. } </syntaxhighlight> : A exceção é função anônima de uma linha: <syntaxhighlight lang="csharp"> SPRT A 5 { /* Única instrução. / } </syntaxhighlight> === Modificadores de campos e funções === Modificadores de acesso (<code>protected</code>, <code>private</code>) devem vir primeiro ao declarar campos e funções: <syntaxhighlight lang="csharp"> protected int myField; private void MyFunction() {} </syntaxhighlight> * Escopos devem vir em segundo: <syntaxhighlight lang="csharp"> protected ui int myUIField; private clearscope void MyDataFunction() {} </syntaxhighlight> * Para funções, <code>static</code> vem em terceiro: <syntaxhighlight lang="csharp"> protected ui static void MyUIFunction() {} </syntaxhighlight> * Para campos, outros modificadores como <code>readonly</code> e <code>transient</code> vêm em terceiro e podem vir em qualquer ordem: <syntaxhighlight lang="csharp"> private ui transient int myUIField; </syntaxhighlight> === Classes e tipos de dados === * Tipos primitivos devem ser sempre minúsculos: <code>int</code>, <code>double</code>, etc. Tipos não-primitivos como <code>Name</code>, <code>String</code>, <code>Sound</code>, etc. devem usar PascalCase. * Classes, structs e enums devem usar PascalCase e não devem ter números no nome: <code>MyClassName</code>, <code>FMyStruct</code>, <code>EMyEnum</code>. Structs podem opcionalmente começar com prefixo <code>F</code> e enums devem sempre começar com prefixo <code>E</code>. * Use espaçamento correto ao declarar classes: <syntaxhighlight lang="csharp"> class MyClass : MyBaseClass replaces DoomImp { } </syntaxhighlight>