Enhancement: implemented documentation for “codeOnly”-files

[sjorek]

Description is in https://github.com/nevir/groc/issues/114 …

[sjorek]

Dunno with thread you read first, so here is a comment duplicate to ease reading :smirk:

yep … and here we are: 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]

If you decide to merge this, you could leave the issue and/or this request open, so we can discuss a solution for how to sync code and comments (= having more than 1 comment-block and 1 code-block) …

~~… I have something like the typical unified-patch-diff-syntax in mind … the section about “range information”~~

[sjorek]

… another idea to get code and comments in sync: place regular-expressions as markers in the markdown-file to indicate what line of code the comment-segment should start at … sounds easier than the one above … an example:

code:

{
 "a nifty and nice": "json file",
 "with numbers": 1,
 "and booleans: true
}

markdown:

# description of the file

All lines starting and ending with / will be stripped from output and used
as regular expression to match the line of code the following comment
segment should start at. If it does not match at all, the code and comments
being left will be append to the previous segment.

/a nifty/
This parameter is the first property to describe.

/with numbers/
This parameter is the second property to describe.

/and booleans/
This parameter is the third property to describe.

/does not match/
… this will be appended to the segment above.

… actually I like this idea, as I'm writing it down. @kmdavis How about you ?

[sjorek]

~~Attention: this patch should have https://github.com/nevir/groc/pull/116 applied ! Otherwise the nicely documented .groc.json file will be missing on github !~~

You did it, yeah !