Solve the problem of accurate documentation

open-sorcerers / madlib

Madlib: a compile-to-JS language written in Haskell, designed to make writing code a delight

https://github.com/madlib-lang/madlib

BSD 3-Clause "New" or "Revised" License

3 stars 0 forks source link

Solve the problem of accurate documentation #28

Open brekk opened 3 years ago

brekk commented 3 years ago

Code gets written
Documentation gets written
Iterate
See that the documentation isn't in sync with the code?

How do we solve this?

Random thoughts from the dome:

have a magic comment syntax a la jsdoc + @comment shit?
this issue is related to testing and correctness as well
what if you wrote some code, then run a command like madlib testharness some-code.mad, which generates an intermediate file (e.g. some-code.madexample) which represents the contract between the defined types and the tests-to-be-written (or maybe already written, hence the intermediate file) — this could function as both a changepoint for generating documentation, a place to hook unit test functionality, and it would ideally be magically re-generated (a la snapshots / golden tests) so fixtures / examples / documentation / correctness are all rolled into a single pipeline.

brekk commented 3 years ago

Or maybe you have something closer to a C-style header file, and that human-managed file has syntax for how to auto-generate an example / documentation.

brekk commented 3 years ago

Some examples from Julia + D:

brekk commented 3 years ago

Proposed syntax for examples syntax:

add :: Number -> Number -> Number
add = (a, b) => (a + b)
add examples (
  5    |> ???(2, 3) -- Positive Numbers can be added together
  0    |> ???(-100, 100) -- Negative Numbers can be added together
  -100 |> ???(-100, 0) -- Zero is a valid Number
  1.23 |> ???(1, 0.23) -- Floating point Numbers are valid
)

aboeglin commented 3 years ago

As said on slack, I like the proposal very much. I think that should maybe be an inline version of a longer form that can allow easier setup of more complex things to test ? I'm thinking things like setting up a Wish that mimic an API or read some fixtures or something among these lines.

aboeglin commented 3 years ago

Also, already talked about that but I'm not sure where we stopped, I think we should give the option to write examples in a separate file. Maybe we can make it a convention that the name of the file need to match but extension differs like .h in C ? Something like:

Module.mad
Module.examples

Well, I find examples a bit long for an extension. I'd propose mex for Madlib EXamples.