Fix and enhance code segmentation for folded and embedded block-comments

lib/languages.coffee

@@ -15,8 +15,8 @@ module.exports = LANGUAGES =
   CSharp:
     nameMatchers:      ['.cs']
     pygmentsLexer:     'csharp'
-    singleLineComment: ['//']
     multiLineComment:  ['/*', '*', '*/']
+    singleLineComment: ['//']
     ignorePrefix:      '}'
     foldPrefix:        '^'
 
@@ -37,19 +37,52 @@ module.exports = LANGUAGES =
   CoffeeScript:
     nameMatchers:      ['.coffee', 'Cakefile']
     pygmentsLexer:     'coffee-script'
+    # **CoffeScript's multi-line block-comment styles.**
+
+    # - Variant 1:
+    #   (Variant 3 is preferred over this syntax, as soon as the pull-request
+    #    mentioned below has been merged into coffee-script's codebase.)
+    ###* }
+     * Tip: use '-' or '+' for bullet-lists instead of '*' to distinguish
+     * bullet-lists visually from this kind of block comments.  The preceding
+     * whitespaces in the line-matcher and end-matcher are required. Without
+     * them this syntax makes no sense, as it is meant to produce comments
+     * like the following in compiled javascript:
+     * 
+     *     /**
+     *      * A sample comment, having a preceding whitespace per line. Useful
+     *      * to embed `@doctags` in javascript compiled from coffeescript.
+     *      * <= COMBINE THESE TWO CHARS => /
+     * 
+     * (The the final comment-mark above has been TWEAKED to not raise an error)
+     ###
+    # - Variant 2:
+    ### }
+    Uses the the below defined syntax, without preceding `#` per line. This is
+    the syntax for what the definition is actually meant for !
+    ###
+    # - Variant 3:  
+    #   (This syntax produces arkward comments in the compiled javascript, if
+    #    the pull-request _“[Format block-comments
+    #    better](<https://github.com/jashkenas/coffee-script/pull/3132)”_ has 
+    #    not been applied to coffee-script's codebase …)
+    ### } 
+    # The block-comment line-matcher `'#'` also works on lines not starting
+    # with `'#'`, because we add unmatched lines to the comments once we are
+    # in a multi-line comment-block and until we left them …
+    ###
     multiLineComment  : [
-      # This kind of comment is not yet enabled here, but works, if foldPrefix
-      # has been set to something else than '-'.  Then we can use '-' for
-      # bullet-lists instead of '*' to distinguish bullet-lists from this kind
-      # of block comments.  A patch to switch from '-' to '~' has been prepared
-      # and waits for merging.
-      # } '###*',    ' *',   '###',
-
-      # The block-comment line-matcher `'#'` also works on lines not starting
-      # with `'#'`, because we add unmatched lines to the comments once we are
-      # in a multi-line comment-block and until we left them …
-      '###',     '#',    '###'
+      # Syntax definition for variant 1.
+      '###*',   ' *',   ' ###',
+      # Syntax definition for variant 2 and 3.
+      '###' ,   '#' ,   '###'
     ]
+    # This flag indicates if the end-mark of block-comments (the third value in
+    # the list of 3-tuples above) must correspond to the initial block-mark (the
+    # first value in the list of 3-tuples above).  If this flag is missing it
+    # defaults to `true`. If true it allows one to nest block-comments in
+    # different syntax-definitions, like in handlebars or html+php.
+    strictMultiLineEnd:false
     singleLineComment: ['#']
     ignorePrefix:      '}'
     foldPrefix:        '^'
@@ -68,6 +101,9 @@ module.exports = LANGUAGES =
       '<!--', '', '-->', # HTML block comments go first, for code highlighting / segment splitting purposes
       '{{!',  '', '}}'   # Actual handlebars block comments
     ]
+    # See above for a description of this flag.
+    strictMultiLineEnd:true
+    # This one differs from the common `ignorePrefix` of all other languages !
     ignorePrefix:      '#'
     foldPrefix:        '^'
 
@@ -95,8 +131,8 @@ module.exports = LANGUAGES =
   JavaScript:
     nameMatchers:      ['.js']
     pygmentsLexer:     'javascript'
-    singleLineComment: ['//']
     multiLineComment:  ['/*', '*', '*/']
+    singleLineComment: ['//']
     ignorePrefix:      '}'
     foldPrefix:        '^'
 

lib/styles/default/behavior.coffee

@@ -317,8 +317,10 @@ $ ->
       else
         search$.val ''
 
-  # Make folded code blocks toggleable
-  $('.code.folded .marker').each (index, marker) ->
-    marker$ = $(marker)
-    marker$.click (evt) ->
-      marker$.parent().toggleClass 'folded'
+  # Make folded code blocks toggleable; the marker and the code are clickable.
+  $('.code.folded').each (index, code) ->
+    code$ = $(code)
+    code$.click (evt) ->
+      code$.toggleClass 'folded'
+      evt.preventDefault()
+      return false

lib/styles/default/docPage.jade

@@ -29,7 +29,7 @@ html(lang="en")
           - if (segments[i].highlightedCode != '')
             - if (segments[i].foldMarker != '')
               .code.folded
-                .marker.wrapper
+                .wrapper.marker
                   span.c1!= segments[i].foldMarker
                 .wrapper!= segments[i].highlightedCode
             - else

lib/styles/default/style.sass

@@ -636,16 +636,22 @@ input[type="search"]
 
 // ## Code folding
 
+.code .marker, .code .marker.wrapper, .code .wrapper.marker
+  display: none
+
 .code.folded
   .wrapper
     display: none
+    cursor: default
 
   .marker
     +border-radius(0.2em)
     +box-shadow(#2f3539 1px 1px 1px 0)
-    display: block
+    display: inline-block
     border: 1px solid #73787f
     padding: 0.2em 0.5em
+    margin-left: -0.5em
+    margin-right: -0.5em
     background: #58616b
     font: 12px 'Droid Sans Mono', Menlo, Monaco, monospace
     text-shadow: #2f3539 1px 1px 0px