Documenting Mixins with Maps

[gisu]

Hi i sitting for my own Framework that need to documented. What is the best Way to document Mixins with Maps - like this:

/**
 * Generate the Offset Width for a Colum
 *
 * @param  {map}  $offset - Setup Vars
 *                         :size [number]
 *                           => The required colum size
 *                         :max [number]
 *                           => Max Colums
 *                         :direction [value]
 *                           => The Direction off the Offset (default: left)
 */
@mixin grid-offset($offset) {

  // Setup Default Vars
  $offset: map-merge((
    size: 1,
    max: 12,
    direction: left
  ),$offset);

  // Cleanup Max
  $m: strip-units(map-get($offset,max));
  // Cleanup Colums
  $c: clamp(strip-units(map-get($offset,size)), 0, $m);

  @if map-get($offset,direction) == left {
    margin-left: grid-size($c,$m);
  } @else {
    margin-right: grid-size($c,$m);
  }
}

Sassdoc read only the first line (@param) the rest is lost. Is there a possible solution for?

Also i had some Mixins, with Vars that holds posible Values like: 'top', 'left', 'bottom', 'right', 'number' and 'bool'. Is it possible to include linebreaks, so the Description is more readable?

[KittyGiraudel]

First is duplicate: #25.

Second, linebreaks where? In the description? Description is parsed as markdown, so double space + cariage return should do the trick.

[gisu]

First ok takes a while.

Second can you Explain? When i want to make a break in Markdown i include a <br> but the parser would Escape it.

/**
 * Include the Breakpoint from the Map
 *
 * @param  {*}  $target - The required Breakpoint
 * @param  {*}  $mode - The Media Querie Mode. Values: 'between', 'max', 'min' ,'auto' (default - setup with mobile-first:true/false)
 * @param  {Map} $list ($kittn-breakpoint-map) - Connection to the Breakpoint Map
 */
@mixin break($target, $mode: auto, $list: $kittn-breakpoint-map) {...}

[KittyGiraudel]

Oh. Sorry, I didn't get it was in a parameter description. Undoable at the moment. If you think it's a key feature, you could open a ticket for this, and wait for @FWeinb's answer.

[ajmueller]

@gisu and @hugogiraudel, was a ticket ever opened for this? I could not find one when browsing the issues. We've come across a similar situation in our framework.

We currently use a method similar to @gisu for passing in options and merging defaults, but with our move to Sassdoc 2 we are exploring a slightly different method whereby the defaults are defined as a parameter to the function or mixin. There are a couple downsides to this method:

1. The $defaults map really shouldn't be a parameter to the function or mixin, but this is how we can get it documented. It should be defined within the function, similar to the common pattern for jQuery plugin development most of us are familiar with.
2. If the $defaults map has more than a couple keys the display of the Parameters table gets distorted due to the lack of line break support in the Default Value column.

I'm happy to make an issue for this to get the discussion going and I have some ideas for what we're looking for, I just wanted to make sure such an issue hadn't already been created.

[pascalduez]

Let's follow the discussion in #386