nevir/groc — pull request #110 by sjorek (2013-09-11 16:27:23+00:00)
Title: Enhancement: >>a series of multiple<< embedded comments (even collapsible)

Actually this pull-request is an enhancement of @achingbrain 's pull-request https://github.com/nevir/groc/pull/95 which has already been merged into groc. It consists of three changes, but before I go into detail, have a look at the result of what I'd would like to enhance: open http://sjorek.github.io/groc/utils.html … and scroll down to the line stating ***Unfold this code -->***

This change does not come out of no-where - I already implemented support for [Literate Coffeescript](http://coffeescript.org/#literate) which I'm going to offer as pull-request soon. During development I discovered, that sometimes one wants to embed ***a series of multiple comments*** in the code of generated documentation. The current implementation creates for each embedded comment a separate segment, hence it inserts an empty line after each of these comments. [This example](http://sjorek.github.io/groc/namespace.html) ([code here](https://github.com/sjorek/groc/blob/master/lib/namespace.litcoffee)) contains a usage scenario (at **HERE IT IS**) where this leads to wrong (looking) results:

------------
…
A namespace like …

LANGUAGES.language.namespace.types = [
"Exact.Match": "http://…/docs?type={type}"
]

… with an input like …
**HERE IT IS:**

# } @property dummy
# } @type {Exact.Match}
dummy: null

… outputs …

…

--------------------------------

So now some descriptive details:

1. Obviously I implemented support for a series of comments embed into code with `# } …` preserving the previously
introduced folding feature currently activated via `# - …`.
2. I changed the visually via CSS added folding prefix from a series of three single dots `. . .`
to the proper triple-dot continuation-sign `…`
3. To avoid clashes with markdown's bulletlists, which can not only start a the star `*` but also with a dash `-`, I
changed the foldPrefix to tilde `~` and updated all comments accordingly. @achingbrain This obviously breaks
anything you've done so far, and requires you to update your code accordingly. As an alternative you could use
the new `--language`-option to specify a path to an old version of the language-file which still uses the dash `-`. Or
you can force me to do so the other way around … I don't insist in this change, but existing Literate-Coffeescripts
rely on the dash as bulletlist-indicator a lot … an I think it would be wise, to avoid clashes with markdown.

I hope you you all agree with these changes. As code-folding is not that long available in groc, there is a good chance, that it is not yet too widespread.

Stephan :smile: