Support for preprocessor functions and mixins

[Anahkiasen]

It seems like mixins and functions, at least in SASS/SCSS, aren't parsed correctly.
Take the following simple block :

// @arrow-bottom($size, $color)
//
// Generates an arrow on the bottom of the block
//
// $size  - The size of the arrow
// $color - Its color
//
// Styleguide 1.2.2.

As kss-node is interpreting the arguments as modifiers, it doesn't display them without a provided markup.
Mixins and functions shouldn't have any markup – ever – and thus the parser should skip straight to the modifiers and display them as arguments.

[r4j4h]

I would like to add this from http://warpspire.com/kss/syntax/

---

Each documentation block should have a description section, parameters section, and compatibility section. The description section follows the same guidelines as style documentation.

The parameters section

If the mixin takes parameters, you should document each parameter and describe what sort of input it expects (hex, number, etc).

// $start - The color hex at the top.
// $end - The color hex at the bottom.
The compatibility section

You must list out what browsers this helper method is compatible in.

// Compatible in IE6+, Firefox 2+, Safari 4+.
If you do not know the compatibility, you should state as such.

// Compatibility untested.

[r4j4h]

Just an update, with 0.3.6: modifiers are coming through as paragraphs, as are compatibility sections.

[cvn]

I would just like to add that LESS mixins are not parsed correctly either. The entire parameters section just turns into a single line of text.

[dotherightthing]

+1 - I'm seeing this too.

[dotherightthing]

I found that adding ~ after my parameters list prevented kss-node from outputting the each parameter as a modifier.

Example:

/*
Mixins: Grid - 2 column with gutter

Custom grid, fully fluid to 100% of the container

Usage:

* `@include grid-flexi-x2(66/407, 11/407, 330/407);`

Layout:

* 1 row, containing 2 columns, separated by 1 gutter

Parameters:

* `$col1_width_nounit` - width of first column, divided by total width of container
* `$gutter_width_nounit` - width of gutter, divided by total width of container
* `$col2_width_nounit` - width of last column, divided by total width of container

~

Markup:
<div class="debug">
    <div class="grid-flexi-test">
        <div class="col">
            column 1
        </div>
        <div class="col">
            column 2
        </div>
    </div>
    <!-- /.grid-flexi-x2 -->
</div>

Styleguide 1.3
*/

[tomasdev]

👍

[ogbaoghene]

Hello, I too ran into this issue, my parameters output on one line as a paragraph. I use Sass, is there a workaround for Sass users? Thanks.

[JohnAlbin]

As kss-node is interpreting the arguments as modifiers, it doesn't display them without a provided markup.

Oh! I was trying to figure out how to get kss-node to tell the difference between a preprocessor helper docblock and a regular docblock. And I think that's the key!

If the docblock has a block that looks like modifiers, but has no markup block, then kss-node can display those as parameters instead of modifiers.

[MadLittleMods]

👍

[JohnAlbin]

Fixed!

[MadLittleMods]

Thanks :) - Is there any chance this could be published to npm before the full 2.0 checklist todo is done?

I'll install from the repo for now: npm install kss-node/kss-node

[varemenos]

@MadLittleMods You dont need to wait for the final v2 release, just wait till "2.0.0-alpha.5"

[MadLittleMods]

I just tried the latest code and it doesn't seem to work. I am using Sass scss. Installed via: npm install kss-node/kss-node#master

I grabbed this example from the gh-pages demo, also on the KSS site

// Creates a linear gradient background, from top to bottom.
//
// $start - The color hex at the top.
// $end   - The color hex at the bottom.
//
// Compatible in IE6+, Firefox 2+, Safari 4+.
@mixin gradient($start, $end){
  ...
}

The only way I can get it to parse is if I add a // Styleguide 6.4 section declaration on the last line.

In that example, kss-node uses the description as the the header.

If I add a a header(which is repetitive because it is right there in the mixin), then it lumps the description, parameters, and compatibility into the description. I see that @JohnAlbin added a section declaration in his commit and a title.

Should it work without a header?

Also there is a kssParameter which is available through kssSection.parameters() but there is no compatibility method to retrieve the "Compatible in" section. Is this assumed to be lumped in with the description.

[JohnAlbin]

FYI, I'm using this feature already on a production web site. It's included with https://github.com/kss-node/kss-node/releases/tag/v2.0.0-beta.1

I've already opened a github discussion in the kss queue about the problem with showing a preprocessor example that doesn't have a Styleguide [ref] declaration. https://github.com/kneath/kss/pulls How does that even make sense? If a CSS comment doesn't have a Styleguide [ref] how can it be a KSS doc block? How would any kss parser know where to put the documentation if the user doesn't define where in the style guide hierarchy the preprocessor docs should go. The spec is too vague here.

The latest docs I wrote for kss-node v2 include an annotated spec at https://github.com/kss-node/kss/blob/spec/SPEC.md . That spec is clearly noted in the README, but won't appear on the kss-node homepage until v2 is released and the master branch becomes the default branch (instead of 1.x.) That will happen sometime in the next week.