Enhancement: document `codeOnly`-files

[sjorek]

I'm not yet satisfied with the current codeOnly-implementation, introduced by my own pull-request: https://github.com/nevir/groc/pull/109 . The undocumented code looks good, no question, but having the option to document it by other means would be better.

I'm thinking about placing a *.json.md (obviously containing pure markdown) just besides the *.json files, detecting their availability, and if available use them to render the documentation. Of course I would implement it more generic and take the filename of the current codeOnly-flag enabled file, appending a .md to it and go on as described above. This part would be really easy to implement, _but how to avoid doubled index entries_, if someone also renders any markdown-file by specifying **/*.md. That's the point where I'm stuck and need more research or an idea from someone else …

  :thought_balloon: :flushed:

[kmdavis]

there would also be a tricky part trying to associate documentation blocks with code blocks. it might just be 1 big comment & 1 big code block

[sjorek]

yep … and here we are: https://github.com/nevir/groc/pull/115 ; 1 big comment-block and 1 big code-block, but enough to document the json-files for now … better than no documentation at all … (and no more ugly captions in the index too !)

[sjorek]

latest comments are in the pull-request mentioned above … https://github.com/nevir/groc/issues/115