Add ability to define file-level annotations

[kaelig]

In the SassDoc for Guss, which is essentially multiple libraries put together, I wanted each library to be part of its own group (making a clear separation between, say, CSS3 mixins and typography styles).

I ended up writing @group my-component a lot, since it had to be in all of the mixins / variables / functions that I documented. For example, in this file, you'll find @group typography 16 times.

To be more dry, is there something we could do about it, like a comment at the beginning of the file:

/**
 * @group typography
 */

That would set the group of all the mixins/variables/functions in the file to "typography" (unless set otherwise)?

This implementation is barely a suggestion. The important part of this open ticket is the problem of code repetition, not the bit of code above.

[pascalduez]

I can only +1 on this one, although I did not have has many items as you in my libs, I already found it quite tedious (and error prone) to add groups to each of them.

I guess we would need a different syntax for per item group and per file group.

/**
 * @global-group typography
 */

This features would obviously had a bit of complexity to the code, but for good.
That might be a job for sassdoc-filter.
There's already the file property which can help in this process.

[alademann]

To me, this relates to the discussion about Documenting BEM / Modules... Being able to define a group of related "things" with one docblock comment would be sweeet.

[mattdrose]

I think it's pretty common practice for devs to organize their tools/modules into separate files. It'd be cool if the documentation had an option to automatically group things based on the file. You could use something similar to JSDoc's @file tag.

Furthermore, it'd be even better if you could have a higher level of grouping based on directories. You could use a navigation in the header to jump between these directories.

I've been using DSS to achieve exactly this at work. It gives you the ability to document large frameworks in an organized manner.

Here's a screenshot of what I setup—notice the menu:

[KittyGiraudel]

2.0 or before if we can make it, but no rush on this one.

[valeriangalliat]

+1

I think this should reside in the parser since it's all about parsing another comment type... sassdoc-filter shouldn't have to open the file again to make its own parsing for the global comment.

Maybe package this as an extension to the parser? I don't know enough scss-comment-parser to know what's the best solution for this. But if we can do like JSDoc with @file, it would be great.

[pascalduez]

I like the @file annotation as well.

scss-comment-parser should obviously parse it, but should not be responsible for the later data massaging.

sassdoc-filter should of course not open any file, but I though it would need to make the distinction between @file and @group items.

Let's try to define the behavior clearly:

• If @file is present at the top of a file, all items in that file will inherit this file/group.
• If an item in such a file has an @group annotation, it will override the @file for that item.
• We might need to introduce a new property in the view.json .sassdocrc for @file friendly names ?

I'm wondering how this could go along nicely with nested groups #135 and BEM #18
If an item override @file with an @group should this group be considered a top level one, or a sub group of @file ...

[mattdrose]

I like that idea of having @file and @group as two separate things, rather than having it override. 1) I think it's confusing because it's not intuitive that these two things are related and 2) separating them gives more flexibility as to what you can do with the extracted data.

Maybe in the @file comment block, you could set things like @author, @copyright, @group, etc. which would act as global settings to the file. Then you could override them if you specify them later in the file for individual items.

Also, as per grouping, we might be able to learn from the different tags JSDoc uses for grouping: @namespace and @module. They use some interesting techniques for nesting (@namespace NamespaceName.ChildItemName). Also, it's interesting that when you set @module, it assumes everything in that file is a part of that module unless otherwise specified.

[KittyGiraudel]

I would like this feature to be one of the first we work on for v2 (or even before if we can implement it without breaking anything). I feel like having a way to set file-specific annotations is a real plus for architecture that has a huge number of files.

On the top of my head, following annotations might be useful at a file level:

• @access
• @author
• @deprecated
• @group
• @since
• @todo

Name and description might also come in handy at some point.

On the other hand, some annotations make absolutely no sense at a file level (e.g. @param, @return...). We need to find how to handle those.

[valeriangalliat]

To make it simple, i'd say: every file annotation is affected to all items of the file, unless an item annotation overrides it, or unless there's specific code about some annotations (I think of @group in particular, that would be appended instead).