Add ability to document maps in a DRY way

[MattDiMu]

Sassdoc is great. I don't like, however, the way maps are documented, because I need to duplicate both - the name of the property as well as its value.

/// defines the colors used in this project
/// @type Map
/// @prop {color} primary [red] - used for navigation and other links
/// @prop {color} secondary [blue] - used for backgrounds
$colors: (
  primary: red,
  secondary: blue
);

I've read the discussion #25 about the original implementation, there were valid arguments to implement it the way it currently is and this implementation should definitely Stay. It would be great, however, if it could be enhanced with some sort of inline documentation like

/// defines the colors used in this project
/// @type map
$colors: (
  primary: red, /// used for navigation and other links
  secondary: blue /// used for backgrounds
);

Cons:

• Different way of annotating
• I've got no idea how difficult it would be to implement it

Pro:

• more maintainable and less error-prone (it already happened to me multiple times, that i forgot to update the annotation after changing the default value of the map, especially if it's a large map and i have to scroll up to reach the annotation)
• less to write
• code is much more readable, especially (!!!) on large maps (e.g. configurations)

Personally I see SASSDOC not only as generator for a fancy documentation, but also as documentation guideline, defining the documentation syntax, which makes working in a team much easier. If I need to look after a variable/mixin/function, I often use the editor-shortcut to go to the desired file instead of opening sassdoc in my browser, as it's faster and I'm sure, that I'm not the only one. So readability, making it easy to find the corresponding annotation to a variable/property, is important to me.

PS Some sort of (optional) "inline" documentation might be useful for variables as well, as it feels "clearer" to me. Something like

$color: #FFAAFF; //< {color} description
$font-size: 10px; //< {number} description

What do you think, any opinions?

[pascalduez]

Hi @MattDiMu,

you put forward pretty good arguments here, and real usage concerns.
Especially the maintenance involved to keep key-values and annotations in sync and how comments should also help read the code without the need to refer at the compiled result.

However this might not be trivial:

1. As exposed in Support for maps properties #25, we prefer not to infer in the way code is written/formatted.

   I don't want comments that enforce a specific coding syntax.

2. Parsing comments entangled with code turns out to be really tricky and fragile.

Around the same topic I've been playing with a kinda literate programming style theme for SassDoc (not released), and it's not a small task.

Let's see what we can do.

PS: Do you have online examples of such maps ?

[valeriangalliat]

Maps

I agree having this kind of inline documentation for map properties would be great.

My first thought was that SassDoc is not at all designed for this kind of comments. Currently, the parser (CDocParser, extended by ScssCommentParser) searches for block comments, and associate them with a context-less item below (function, mixin, variable, placeholder). Context-less because the type and name can be determined on the declaration line, there's no need to maintain some kind of context to identify it. Inline comments in maps are not compatible with this.

However, there's another way to reason about this; SassDoc is able to autofill some annotations by looking at the code of a documented item. So this problem could be "just" about autofilling the @prop annotations. The @prop autofill would have its own parser, with its own kind of comments to autofill the description and type, and would be able to traverse a nested map structure (with the required context to keep track of the current absolute key).

So, technically a feature like this could fit in SassDoc without any modification on how SassDoc works internally (and I was not convinced it could, at first sight). The only difficulty is to write the map parser to convert these inline comments to autofilled regular @prop (and first, agree on what the inline comments will look like).

Variables

Though, we cannot extend the above solution to inline documentation for variables, because we can't autofill an undocumented item. But unlike map properties, variables don't require to keep track of the context, so supporting a top-level inline comment could gracefully fit in how the parser works currently.

I'm not sure about the syntax, but if we want to develop this idea:

$foo: 42; /// @var {Number} The answer.

... would just be a different way to express:

/// @var {Number} The answer.
$foo: 42;

And yes, we don't have @var yet, but I'd rather add a @var annotation than having another totally different kind of comment without annotation that autofills multiple annotations based on the item type.

Conclusion

While there's a significant amount of work required to implement this (for both maps and variables), the features can be designed in such a way that we don't need to change anything about how the core works.

---

Since @pascalduez already answered since I began writing this, I'd just like to comment a point:

As exposed in #25, we prefer not to infer in the way code is written/formatted.

I don't want comments that enforce a specific coding syntax.

Supporting inline comments for maps autofill and variables is not enforcing anything; people can still use regular annotations in block comments, but they can use inline syntax if they want, because it has several advantages over block annotations.

[MattDiMu]

@valeriangalliat Yes, that's what i meant: Inline annotations should definitely be just an an alternative way of annotating, no replacement!

@pascalduez Unfortunately I do not have any online projects, where sass maps are documented with sassdoc. In my companies projects i currently do it by ignoring the sassdoc convention at maps, as the inline comments are shown in the code section and this is simply more maintainable and readable: