Fix annotation parsing in nested comment blocks

[davidknezic]

I need to be able to document classes that are nested. Like in this example:

@each $breakpoint in map-keys($grid-breakpoints) {
  @include media-breakpoint-up($breakpoint) {

    /// text
    ///
    /// @example
    ///   <div class="fade-in-xs-up">
    ///     <span>Test</span>
    ///   </div>
    .fade-in-#{$breakpoint}-up {
      // ...
    }
  }
}

This works, except for all the annotation handling. Annotations don't get recognized and all land in the description. The reason for that is how indented comments get returned from CDocParser.CommentExtractor. The snippet above would result in this output:

{
  "lines": [
    "text",
    "   ",
    "    @example",
    "      <div class=\"fade-in-xs-up\">",
    "        <span>Test</span>",
    "      </div>"
  ],
  "type": "line",
  "commentRange": {
    "start": 43,
    "end": 48
  },
  "context": {}
}

The filterAndGroup function then filters and groups the lines and uses the following to detect annotations:

lines.forEach(function (line){
  var isAnnotation = line.indexOf('@') === 0;

This of course doesn't work, because some of the lines are indented.

This fix trims the comment lines to detect annotations, uses the trimmed lines when pushing into a new group and then keeps using the untrimmed line so intentional indentation doesn't get lost (ex. in @example source code).

[pascalduez]

Hi,

thanks for the PR!
The changes looks good to me. Although I sorta remember we stated long time ago that nested code documentation was not possible/desired in the current state of things... Most probably inside functions, mixins declarations. Well, if it works without breaking things that's a pretty nifty patch :)

Could you please write a few unit tests so that the feature is clearly defined?

Also running the unit tests from the main sassdoc lib with that patched dependency would be quite reassuring.

[deap82]

What's the latest on this?

I'm writing my scss with bem conventions like this:

/// This works good
.some-block {
    /.../

    /// This also works
    &--small {
        /.../
    }

    /// This example annotation does not work
    /// @example html
    /// <div class="some-block some-block--large">My large block</div>
    &--large {
        /.../
    }
}

I'm using the Herman theme (https://github.com/oddbird/sassdoc-theme-herman) and use a @group for each block level class, so documenting "&--small" works really well as I get a page for each block level, and therefore it's clear that the &--large is a documentation of .some-block--large.

But I'd really need the @example annotation to work even if it is indented...

Update:
Well, I'm using gulp, so installed gulp-replace and did this in my sassdoc gulp task:

	return gulp.src(scssPaths)
		.pipe(replace('\t\t\t/// @', '/// @'))
		.pipe(replace('\t\t/// @', '/// @'))
		.pipe(replace('\t/// @', '/// @'))
		.pipe(sassdoc(options));

[pascalduez]

What's the latest on this?

Needs unit tests.