Maintaining schelp files in quarks for me has always felt a bit clunky: as long as you don’t have any .schelp file for a given class, the SCDoc help system will generate a template for you to get started (which, admittedly, is very helpful, although it tends to quite randomly mix up the order of things).
The real trouble starts when you continue developing your software and the .schelp files become outdated. If you add a few new methods, e.g. the help system will list them as undocumented functions, but you don’t get any template to help you fill them in, and finding where to add new stuff in the schelp file can be a bit tedious.
To address this problem I made a python tool called “whelk”. (Why whelk? Because “schelp” is the Dutch word for “shell”, which makes me think of holidays, sun, sea and beach. A “whelk” is an edible sea-snail, and so it has a “schelp”. Nevermind.)
“whelk” is pretty dumb as far as tools are concerned: it collects all comment sections from the .sc file that parse as valid TOML syntax, concatenates all these into one long TOML string, and then parses that string into a tree structure and unparses the tree structure with the help of a template into a schelp file.
Having the documentation directly in the code scratches several of my itches:
- the code is better documented for someone trying to read it
- no need to mentally context switch between code files and schelp files
- much easier to keep code and schelp in sync
Why TOML syntax you might ask?
- It’s lightweight: easy to write and read by humans, easy to parse for a computer
- SCIDE’s code reformatting doesn’t make it invalid (unlike e.g. YAML that depends on indentation)
If this sounds interesting to you, have a look at the tool here:
To see a project where all its schelp files are generated with whelk, have a look here: