Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Add ability to define file-level annotations #190
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
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.
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 */
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.
I think this should reside in the parser since it's all about parsing another comment type...
Maybe package this as an extension to the parser? I don't know enough
I like the
Let's try to define the behavior clearly:
I like that idea of having
Maybe in the
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 (
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:
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.
changed the title from
Global @group override in a file
Sep 7, 2014
One thing I was thinking about the other night: item-specific annotations should always override the file-level annotations, not pile up. For instance, a
Edit from @HugoGiraudel: the idea is to give users a way to define annotations that are being applied at a file level. For instance, you could apply
I think we could do it as follows:
First define a "poster" comment block like:
You see there are at least two
Than we need to think about how we want these comments to work.
I would go for 1 because you should group your sass code by file rather than by specify section in one file, but that is just me.
I hope you get the idea here.
I am on implementing it. I decided to have this order of specificity:
So to give some examples:
While implementing it solution