Feature request: Allow to add description to groups

[xi]

I would like to add an introductory text to a group. In my case, there is one group per file, so my initial idea was to use the (so far unused) poster description. However, I realize that this does not work in general.

I would be open to doing the implementation myself. Unfortunately I do not really know where to start.

[pascalduez]

Hi,

this is currently doable by using custom annotations and theme.

For this to land into Sassdoc's core it probably means creating a new annotation or extending the current @group one, then extend the default theme to support it (or not).
It would need to gather a bit of interest and validation beforehand though.

[xi]

Thanks for the feedback! I tried two implementations:

• Adding a new @groupDescription annotation (https://github.com/xi/sassdoc-theme-default/commit/77fb3b16e789e76e326c8ac983cabcd80dcd2120)
• Overwriting the @group annotation (https://github.com/xi/sassdoc-theme-default/commit/c0b542f630822ff6100935a77c84e1a92be43627)

Do you think any of these has the potential to be included in sassdoc?

[robsonsobral]

This could be a great addition.

[midorikocak]

Can you make a pull request?

[xi]

I am waiting for feedback from the maintainers which approach I should implement. If you would like to raise the priority of this issue a "thumbs up" is probably the best you can do.

[pascalduez]

Out of the blue, I would say extends the current @group annotation.
@xi Could you please give us samples of how this would look like?
Usage sample of the patched annotation, how it renders in the default theme etc.

Looking at current annotations we have the syntax could be:

@group name description

OR

@group name - description

WDYT?

[xi]

I use the second option (https://github.com/xi/sassdoc-theme-default/commit/c0b542f630822ff6100935a77c84e1a92be43627) in my project sass-planifolia (source/rendered).

[pascalduez]

@xi If your whiling to open a PR on the sassdoc repo, patching the @group annotation, that would be rad.

I'm just wondering about the data interface though, as I can see you introduce a new groupDescriptions key.
I'm wondering whether keeping everything on group would be better.
So
Annotation without description: string
Annotation with a description: object

{
  group: [
    'withoutDescription',
    { name: 'withDescrption', description: 'Lorem ipsum dolor sit amet' },
  ]
}

[pascalduez]

sassdoc@2.6.0 Thanks a lot @xi !

Please test the feature and report any issue.