google / google/codeworld

Improved documentation for builtin symbols

Offen
#814 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
enhancement
Vorherrschende Sprache
Haskell
Sterne
1.3k
Forks
201
PR-Merge-Kennzahlen
Keine gemergten PRs in 30 T.

Beschreibung

Now that we have more visible documentation in the editor, it's conspicuous how much the documentation is missing for a lot of builtin symbols. It would be good to add documentation (which just means haddock in the codeworld-base module) for all these definitions.

At the same time, I should rewrite the existing documentation to be clearer about function arguments. We should adopt this style for the first sentence of every function:

@thickArc(angle1, angle2, radius, thickness)@ is a @Picture@ of an arc
between the given angles, with the given radius and line thickness.

The documentation can go on to give examples and such, but that first sentence clarifies what each argument means in a precise way.

Beitragsleitfaden

Beitragsleitfaden öffnen

Rechercherichtung

Beginne im Modul codeworld-base und überprüfe die Definitionen der integrierten Symbole sowie deren vorhandene Haddock-Kommentare. Erstelle ein Inventar der Definitionen ohne Dokumentation und überarbeite anschließend die Funktionsdokumentation so, dass jeder erste Satz die Argumente im gewünschten Stil erklärt. Erledigt ist die Aufgabe, wenn die Definitionen der integrierten Symbole mit Haddock-Dokumentation versehen sind und die vorhandenen Beschreibungen ihre Funktionsargumente eindeutig definieren.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
haskell
Bereich
documentation
Issue-Typ
Dokumentation
Schwierigkeit
4/5
Geschätzter Aufwand
Über eine Woche
Aktivitätsstatus
Veraltet
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
35/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.