search

gelisam / klister

an implementation of stuck macros
BSD 3-Clause "New" or "Revised" License
132 stars 11 forks source link

do not document hygiene (was: add copious comments to the hygiene example) #181

Closed gelisam closed 1 year ago

gelisam commented 1 year ago

I'm on a quest to make Klister more approachable by having the README link to examples of each feature, with comments explaining what's going on.

gelisam commented 1 year ago

Looking at my own PR, it seems a bit silly to waste time explaining what hygiene is, I should instead focus on documenting the parts which makes Klister special.

Or perhaps on the contrary, since Klister is a mix of Racket and Haskell, it is worthwhile to spend a bit of time explaining one half of the language to users whose background comes from the other half?

gelisam commented 1 year ago

I have now changed my mind and this PR is now doing the exact opposite of what it did originally: instead of adding a copious amount of comments explaining hygiene, the word "hygienic macros" no longer links anywhere, the README now just assumes that people know how to google terms they don't understand. This allows the guide to focus on Klister itself.

The "Custom syntax" link can stay, because it doesn't just repeat the an explanation of what a macro is from somewhere else, it also shows what macros look like in Klister. The comments should probably be much shorter though.

The "easy-to-override hygiene" link can stay, because it specifically shows what is Klister's syntax for overriding hygiene.

The "Custom languages" link can stay, because it specifically shows how to build #langs in Klister.

The "Syntax objects" explanation (currently TODO) should remain because it will explain what Syntax objects are in Klister and how they differ from Racket's.

I think the "module system" and "phase system" explanations (currently TODOs) should probably be merged into a single example explaining meta, phases, and Klister's syntax for imports and exports.

I think the "parametric polymorphism", "algebraic datatypes", and "type inference" explanations (currently TODOs) should also be merged into a single example demonstrating the syntax for defining datatypes and polymorphic functions.

The "monad" explanation (currently TODO) should remain because it shows how we do monads in Klister, namely via explicit dictionary passing.

The "Type-providing macros", "Type-aware macros", "Stuck macros", and "Problem-aware macros" explanations (currently TODOs) should of course stay because they are from the "Features which make Klister special" section.

gelisam commented 1 year ago

My original PR would have warranted a review, but not what it became. Merging.