Fork me on GitHub
#docs
<
2018-02-15
>
tsulej22:02:44

Ok, finally refactored my attempt to enhance doc writing with more metadoc tags. What is done: in place examples (can be tests also), categorization, code snippets (reusable by examples), constants section. Also made custom Codox writer to have it work without any new tools.

tsulej22:02:45

And example namespace with all (I hope) features currently implemented.

tsulej22:02:56

it has no documentation yet

tsulej22:02:39

waiting for your criticism

arrdem23:02:31

I do like the categories idea! I’ve got my own similar shim I’m using for my shelving project which checks for ^:categories #{} on every public var and uses that to partition vars into different doc files.

arrdem23:02:06

I don’t think I like examples inline tho. For https://github.com/arrdem/shelving one of the things I played with was doctests and just supporting arbitrary Markdown tripplequote code blocks inside docstrings. There were some pretty good objections that brought up around the verbosity of putting that sort of metadata inside docstrings instead of having a sidecar registry ala spec that let you separate your examples from your program text.