SassDoc
Setting @name changes 'title' AND source.
When using the following:
/// Breakpoint used for small screens with a screen width less than `$bp--mobile-landscape`
$bp--mobile: 0px !default; // Mobile Breakpoint.
I get the following output:
However, if I set the @name annotation to "Mobile Breakpoint", I'd expect the TITLE of the item in generated docs to change, but not the instance of the variable name in the source code:
/// Breakpoint used for small screens with a screen width less than `$bp--mobile-landscape`
/// @name Mobile Breakpoint
$bp--mobile: 0px !default; // Mobile Breakpoint.
Result:
Expected behavior: I'd expect that ONLY the 'friendly title' displayed above the item to be changed, and not any instances of the variable name inside the source code.
For the sake of clarity, the rational behind the @name annotation was to work around dynamically generated placeholder selectors. We never really had a case where we would rename a variable because we consider that:
- A variable name should be obvious or explicit enough that you don’t have to rename it.
- Having a difference between the variable name and the item name in the docs could be confusing.
That being said, what your report still sort of looks like a bug. @pascalduez?
Agree with you @HugoGiraudel.
But yes, we should probably prevent the annotation from renaming the variable.
Thanks Guys!!
I definitely agree that in the case I demonstrated, variable names SHOULD always be named such that they are self-explanatory, in my case, I was just (while continuing to kick the tires a bit) attempting to give the actual headers for variables a more "reading friendly" title.
While users familiar with SCSS and standards set forth in things like bootstrap/foundation would look at $bp--mobile and say "Hey, $bp denotes a breakpoint, and this one must be for mobile!", I tend to try to write my documentation (when that ever happens!) for the most 'idiot proof' case, so this is why I was trying to get the header to essentially be "THIS IS THE Mobile Breakpoint Variable".
Hey everyone, yeah @name annotation at first glance seemed to me smth for more user-friendly sass documentation and had the same issue as @himerus, would be possible to create another annotation specifically for the case when we want to rename variable name in sassdoc??
Is there any update on this issue? Would love to also know what I could do, now — as a temporary measure, to prevent the @name overriding the variable. Thanks, guys.
