Document variables

[idpaterson]

We're not crazy enough to document every variable in our SASS, but it would be very useful to be able to document what we consider to be the most important variables that other stylesheets can override. We're working on swappable themes, so a few important variables are used heavily.

Not sure on the syntax. I'm generally not a fan of having to provide information that could be derived from the code being documented, but it seems necessary based on the current implementation. I don't think that I would personally use the @default tag since it's very likely to get out of sync with the actual code, so that might not be necessary until the project is able to parse the code associated with each comment to derive that type of info.

// Most colors in the stylesheet are derived from this color.
// @var {Color} $the-color
// @default maroon
$the-color: maroon !default;

// The red value that all colors should use, because that's a useful thing to track...
// @var {Number} $red-value
// @default $the-color
$red-value: red($the-color) !default;

// Specifies whether or not the page can advertise peanut butter.
// @var {Bool} $wants-peanut-butter
// @default true
$wants-peanut-butter: true !default;

// @category ClientATheme

// This client has an allergy.
// @var {Bool} $wants-peanut-butter
$wants-peanut-butter: false;

[eoneill]

Yeah, completely agree. In my original implementation, I was doing something like

// a function that does something
// @param  {Color} $color [red] the color of something...
@function do-something($color: red) {...}

That obviously doesn't scale well. Eventually, I want to integrate the Sass parser into the project, which can derive things like this.

The things it can't derive are the acceptable type (e.g. you might have a variable that can take a string or a boolean, or a variable that can take a string or a list, etc).

I'd also like to support some way of specifying the acceptable values for a parameter. Say, you have a mixin that takes a $method parameter that's a {String}, but the only valid values are margin and padding. Not sure on the syntax of this one, and seems like it would be difficult to derive from parsing the code.

The project also currently doesn't support documenting arbitrary variables (as you're doing here). I could definitely use this myself.

I'll start putting together a roadmap and get this added to the list. Thanks for the ideas!

[joeldrapper]

+1!

[andrefarzat]

+1

[callmeaponte]

+1 !!

[jouni]

One more vote for this feature, I would need this very badly to document our new Sass based theme for Vaadin.

I don't have any experience with Ruby, but is there anything I could help with?

[eoneill]

Unfortunately, this isn't very likely to happen on my end anytime soon. I haven't had any time to work on this (it was a quick, thrown together in a weekend to meet my needs kinda deal).

That said, I'll definitely take pull requests. At some point, when I have nothing else to do, this'll probably get a complete re-write to use the Sass parser instead of some hacked together regex :).