Add ability to document functions, mixins options

[pascalduez]

A tweet points out there is no way to document a Map as parameter currently.
That might be an interesting new feature to add.

Consider the following:

/// Sowieso
/// @param {Map} $options [()] - some options
@mixn whatever($options: ()) { ... }

There's no way to properly document the options map properties.

Some possible solutions (just to illustrate the matter):

Introduce a new annotation

/// Sowieso
/// @options $options - some options
///    @prop {Number} one [1]- option one
///    @prop {String} two ['two'] - option two
@mixn whatever($options: ()) { ... }

Pro: straightforward
Con: How to deal with indentation, nesting

Reference a Map outside the caller

/// Sowieso
/// @type {Option Map}
/// @prop {Number} one [1]- option one
/// @prop {String} two ['two'] - option two
$options: ( one: 1, two: 'two' );

/// Sowieso
/// @options $options - some options
@mixn whatever($options: ()) { ... }

Pro:
Con: Weirdo, complex

EDIT: Was already reported in #111

[valeriangalliat]

We already have @property! http://sassdoc.com/annotations/#property

[pascalduez]

We already have @Property!

But no way to apply @property to a Map as a parameter.

[valeriangalliat]

Alright. Well if we make it compatible with mixin/function parameters, the syntax should remain the same, or as close as possible.

What I propose:

/// @param {Map} $options
/// @prop {String} $options.foo [default] - Description
/// @prop {Number} $options.bar [42] - Description

[pascalduez]

Yeah, much better !
Funny, reminds me the discussions we had when implementing Maps documentation :-)

[ajmueller]

Great proposal @valeriangalliat. That would fit our needs perfectly and be very flexible for others, too. The display in the default theme could get a little bit tricky, though. As I mentioned in #111 when the default value of a map has more than a couple keys, the current display causes the table to get distorted because the Default Value column is so wide. I really like the way you currently output @prop for maps, so I'm sure you'll find a good way to do so.

[pascalduez]

Then there is another issue as mentioned in #111

/// Sowieso
/// @param {Map} $options [()] - some options
@mixn whatever($options: ()) { 
  $defaults: (
    one: 1,
    two: 'two'
  );
}

There is no way to document an item inside an item, and I think that would be a bit problematic to implement.
That's where the Sass !default is supposed to act.

[ajmueller]

Have you all had a chance to discuss this further within the team? Let me know if you have any questions about our needs or implementation ideas.

[KittyGiraudel]

Can I close since we have #111?

[ajmueller]

I believe @pascalduez opened this issue because #111 was closed.

[pascalduez]

Yep, #111 is closed, also we are kind of speaking about 2 different features here if I'm not mistaken ?

• Maps as params
• Maps inside an item

[ajmueller]

I think the two are related in this instance, but are definitely separate features. The way we happen to (generally) use maps as params is to define options that are then extended by a "default" map inside a function or mixin.