Add ability to provide group description

[PixelZombie]

trafficstars

I'd find it handy to have a description for each group to describe what mixins, functions etc. inside of the group are used for. It'll be awesome if you guys could consider implementing this.

Cheers!

[KittyGiraudel]

As of today, this is not planned, but we might consider it.

[KittyGiraudel]

@SassDoc/owners Any input about this?

[valeriangalliat]

It's a sassdoc-extras feature. Like we have group "friendly" names in the configuration file with groupName, we could have group descriptions, and the default theme to display them.

Not sure how to organize this though. Should it be another extra groupDescription, with another configuration key (to not break the current groups: { slug: name } interface)? Or we wait 3.0 and have a { groups: { slug: { name: name, description: description } } } interface?

[FWeinb]

@valeriangalliat why can't we do it in 2.* we just need to support the old syntax too.

[valeriangalliat]

@FWeinb It's not about the syntax. It's about the configuration interface.

Like I'm saying we can not break by adding groupDescription, but I don't really like this. Ideally, in 3.0, we'll be able to have the original groups key to be an object instead of just the name.

[FWeinb]

Stupid me. This is indeed public facing api.

[valeriangalliat]

No problem. :)

It's acceptable to have groupDescription for 2.0, but in 3.0 we'll remove it and have a groups object instead. Not sure we really need this feature right now though.

[Undistraction]

This would be really handy. Something in 2.x would be better than nothing even it it's a little ugly.

[tf]

I also think that having a block of prose at the beginning of a group can add a lot of value. I am not sure though the text itself should live in the config file. Isn't the main idea of a tool like sassdoc to keep the docs close to the code? Ideally the group description would live inside a poster comment at the top of some kind of group directive (see #443).

Thoughts?

[tf]

Maybe if it's a good pattern to apply the @group annotation via the poster comment, it might also make sense to allow using the description from the poster comment as group description? At least the structure of the resulting document would resemble the content of the source file a lot, which I think is a good thing.