Alguns ficheiros de documentação aplicam-se tanto a exercícios de conceito como a exercícios de prática. Estes ficheiros comuns aos exercícios encontram-se no diretório exercises/shared/.docs do percurso:
-
debug.md: explica como um estudante que está a programar no navegador ainda consegue fazer "debugging" (opcional)
-
help.md: contém instruções específicas do percurso sobre como obter ajuda (obrigatório)
-
representations.md: explica que normalizações são aplicadas a uma solução para criar a sua representação (opcional)
-
tests.md: contém instruções específicas do percurso sobre como executar os testes (obrigatório)
O documento de apresentação descreve como estes ficheiros são usados para apresentar conteúdo ao estudante.
Ficheiro: debug.md
Objetivo: Explicar como um estudante que está a programar no navegador ainda consegue fazer "debugging"
Presença: Opcional
O editor no navegador não tem qualquer suporte de debugging incorporado. Se o executor de testes do percurso suportar a captura da saída da consola, o estudante ainda consegue fazer alguma forma de "debugging" e este documento explica como o fazer.
O conteúdo deste ficheiro é mostrado apenas no editor online; a CLI ignora este ficheiro.
Exemplo
# Debug
To help with debugging, you can use the fact that any [console output](https://www.programiz.com/csharp-programming/basic-input-output) will be shown in the test results window. You can write to the console using:
```csharp
Console.WriteLine("Debug message");
```
Ficheiro: help.md
Objetivo: Explicar como um estudante pode obter ajuda
Presença: Obrigatório
Descreve como um estudante pode obter ajuda, especificamente para este percurso (não para todo o Exercism).
O conteúdo deste ficheiro é apenas usado pela CLI, que o inclui no ficheiro HELP.md.
As instruções devem ser curtas e diretas.
Podes criar ligações a recursos como canais do Gitter, fóruns ou listas de correio: tudo o que possa ajudar um estudante a desbloquear-se.
As ligações deste documento podem sobrepor-se às de docs/LEARNING.md ou docs/RESOURCES.md.
Este documento não deve incluir ligações para recursos de ajuda de todo o Exercism (independentes do percurso), uma vez que esses recursos serão automaticamente incluídos no ficheiro HELP.md.
Exemplo
# Help
To get help if you're having trouble, you can use one of the following resources:
- [Kotlin Documentation](https://kotlinlang.org/docs/reference/)
- [Kotlin Forums](https://discuss.kotlinlang.org/)
- [Kotlin Slack Channel](https://kotlinlang.slack.com/): [get invite here](https://slack.kotlinlang.org/)
- [Stack Overflow](https://stackoverflow.com/questions/tagged/kotlin)
- [Kotlin Subreddit](https://www.reddit.com/r/kotlin)
Ficheiro: representations.md
Objetivo: Explica que normalizações são aplicadas a uma solução para criar a sua representação
Presença: Opcional
Quando um percurso tem um representador implementado, é criada uma representação para cada solução submetida.
Este documento deve listar todas as normalizações que o representador aplica a uma solução.
Isto ajuda o mentor quando adiciona comentários de representação.
Exemplo
# Representations
The representer applies the following normalizations:
- All comments are removed
- All import declarations are removed
- The code is formatted
- Identifiers are normalized to a placeholder value
Se o teu percurso tiver um ficheiro docs/REPRESENTER_NORMALIZATIONS.md, recomendamos que ligues as normalizações à secção correspondente desse ficheiro.
Ficheiro: tests.md
Objetivo: Contém instruções específicas do percurso sobre como executar os testes
Presença: Obrigatório
Descreve como executar os testes deste exercício em particular.
O conteúdo deste ficheiro é apenas usado pela CLI, que o inclui no ficheiro HELP.md.
As instruções devem ser curtas e diretas.
O ficheiro docs/TESTS.md pode conter uma descrição mais detalhada sobre como executar os testes.
Exemplo
# Tests
To run the tests, run the command `dotnet test` from within the exercise directory.
Substituição
Nota: isto ainda não está implementado
Os exercícios podem substituir os ficheiros específicos do percurso criando um ficheiro com o mesmo nome no diretório .docs do exercício (por exemplo, .docs/debug.md). Isto só raramente deve ser necessário (se é que alguma vez o será).
