Néhány dokumentációs fájl egyszerre vonatkozik a tanulófeladatokra és a gyakorlófeladatokra. Ezek a feladatokon átívelő fájlok a kurzus exercises/shared/.docs könyvtárában találhatók:
-
debug.md: elmagyarázza, hogyan tud egy böngészőben kódoló tanuló mégis „debugging”-ot végezni (opcionális)
-
help.md: a kurzushoz tartozó utasításokat tartalmaz arról, hogyan kérhetsz segítséget (kötelező)
-
representations.md: elmagyarázza, milyen normalizálásokat alkalmaz a rendszer egy megoldáson, hogy létrehozza annak reprezentációját (opcionális)
-
tests.md: a kurzushoz tartozó utasításokat tartalmaz arról, hogyan futtathatod a teszteket (kötelező)
A megjelenítési dokumentum leírja, hogyan használja ezeket a fájlokat arra, hogy tartalmat jelenítsen meg a tanulónak.
Fájl: debug.md
Cél: Elmagyarázza, hogyan tud egy böngészőben kódoló tanuló mégis „debugging”-ot végezni
Jelenlét: opcionális
A böngészőben futó szerkesztő nem nyújt beépített támogatást a debugginghoz. Ha a kurzus tesztfuttatója képes a konzolkimenet rögzítésére, a tanuló továbbra is tud valamiféle „debugging”-ot végezni, és ez a dokumentum elmagyarázza, hogyan.
A fájl tartalma kizárólag az online szerkesztőben jelenik meg; a CLI figyelmen kívül hagyja.
Példa
# 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");
```
Fájl: help.md
Cél: Elmagyarázza, hogyan kérhet segítséget a tanuló
Jelenlét: kötelező
Írd le, hogyan kérhet segítséget a tanuló, kifejezetten ehhez a kurzushoz (nem az egész Exercism-re vonatkozóan).
A fájl tartalmát kizárólag a CLI használja, amely belefoglalja a HELP.md fájlba.
Az utasítások legyenek rövidek és tömörek.
Linkelhetsz olyan forrásokra, mint Gitter-csatornák, fórumok vagy levelezőlisták: bármire, ami segíthet a tanulónak, ha elakad.
A dokumentumban szereplő linkek átfedhetnek a docs/LEARNING.md vagy a docs/RESOURCES.md fájlban szereplőkkel.
Ez a dokumentum ne linkeljen az egész Exercism-re vonatkozó (kurzusfüggetlen) segédforrásokra, mert azokat a HELP.md fájl automatikusan tartalmazni fogja.
Példa
# 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)
Fájl: representations.md
Cél: Elmagyarázza, milyen normalizálásokat alkalmaz a rendszer egy megoldáson a reprezentáció létrehozásához
Jelenlét: opcionális
Ha egy kurzus megvalósította a representer funkciót, minden beküldött megoldáshoz elkészül a reprezentáció.
Ez a dokumentum sorolja fel az összes normalizálást, amelyet a representer egy megoldáson alkalmaz.
Ez segít a mentornak a reprezentációs megjegyzések hozzáadásában.
Példa
# 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
Ha a kurzusodban van docs/REPRESENTER_NORMALIZATIONS.md fájl, javasoljuk, hogy a normalizálásokat a fájl megfelelő szakaszához linkeld.
Fájl: tests.md
Cél: A kurzushoz tartozó utasításokat tartalmaz arról, hogyan futtathatod a teszteket
Jelenlét: kötelező
Írd le, hogyan futtathatod a teszteket ehhez a konkrét feladathoz.
A fájl tartalmát kizárólag a CLI használja, amely belefoglalja a HELP.md fájlba.
Az utasítások legyenek rövidek és tömörek.
A docs/TESTS.md fájl bővebb leírást tartalmazhat a tesztek futtatásáról.
Példa
# Tests
To run the tests, run the command `dotnet test` from within the exercise directory.
Felülírás
Megjegyzés: ez még nincs megvalósítva
A feladatok felülírhatják a kurzushoz tartozó fájlokat úgy, hogy egy azonos nevű fájlt hoznak létre a feladat .docs könyvtárában (pl. .docs/debug.md). Erre csak ritkán lehet szükség (ha egyáltalán).
