Add ability to nest @group

[KittyGiraudel]

[tjbenton]

The ability to add a sub group to give the ability to organize a large set of groups.
For example if you have 10 @function's that are dealing with numbers, and you have 6 @function's that are dealing with colors you might want to break them up into there own sections. (it could also help with search).

Here is a couple ways I can see this working.

This would be similar to @param

/** 
 * @group {functions} numbers
 */

This is also similar to @param but you wouldn't have to worry about changing up the syntax from what it currently is.

/** 
 * @group functions (numbers)
 */

Here is how you could nest even further

/**
 * @group functions (numbers | fonts)
 */

/** 
 * @group functions (numbers | foo | bar | baz | qux | quux)
 */

You could also replace the | for , if you think its better.
If you don't specify a sub group it would just display at the bottom of the first section(in this case functions).

With the ability to have nested groups you would need the ability to put them in order.

I was thinking it would be really easy to add the group order 1 time at the top of the file your in. I think a map structure is the most readable because it helps you see how the nav would appear on the page.

// _functions.scss
/** @group-order: (
 *   functions: (
 *    "numbers",
 *    "fonts",
 *    "colors",
 *    "icons"
 *   )
 *  );
 */

// _variables.scss
/** @group-order: (
 *   variables: (
 *    "defaults",
 *    "colors",
 *    "buttons",
 *    "misc"
 *   )
 *  );
 */

If you wanted to put a description of the section or sub section you could do that like this

// _variables.scss
/** @group-order: (
 *   variables: (
 *    "defaults": "These variables are used as defaults throughout the site",
 *    "colors": "These declare all the base colors used throughout the site. **Please don't** guess a color value. Instead use `color-get(a, -6)` function to lighten or `color-get(a, 6)` function to darken"
 *    "buttons",
 *    "misc"
 *   )
 *  );
 */

I think it would be nice to have the ability to make the groups and sub groups into accordions so it's a little easier to skip from one section to another. Another option other than accordions would be to set the nav to work similar to bootstraps docs.

[KittyGiraudel]

Thank you very much for the input @tjbenton, although since this is scheduled for 2.0, you might not see any thing happening here before a while. ;)

[alademann]

I'd just like to give a huge +1 to this. I know it may be an "edge case" - but the library I'm working on is quite extensive, and organizing the docs into multiple levels of groups will really be a huge help for me.

Thanks!