Autofill and @require interprets mixin as function

[PixelZombie]

I have a mixin and a function with the same name. Autofill and the @require interprets just the function and doesn't link to the mixin at all.

Example:

@mixin rem(...) {
    ...
}

@function rem(...) {
    ...
}

/// Documented Item
/// @require {mixin} rem
/// or autofill
@mixin line-height(...) {
    @include rem(...);
}

Output:

Requires

[function] rem

Could you guys please have a look into this? Thank you very much in advance!

[KittyGiraudel]

Ping @FWeinb.

[PixelZombie]

I just noticed that the same issue exists for placeholders and mixins with the same name.

[valeriangalliat]

@PixelZombie I'm not able to reproduce with exactly your example.

If I take it as is, I get Item line-height requires rem from type mixin but this item doesn't exist. (and no require output). This is because SassDoc is not aware of undocumented items.

If I add a doc comment to rem mixin, I get expected output (Requires [mixin] rem). Same if I also add a comment to rem function (still requires mixin). And even if only the function have a comment, and the mixin is undocumented, it still links to the (unexisting) mixin!

1. Is this bug still relevant?
2. If you still have the problem, could I see the exact code to reproduce?

[PixelZombie]

Hi @valeriangalliat,
yes the issue still persists. Here's the complete code from the the samples above.

First the function and mixin with the same name:

/// 
/// Converts `px` to `rem`.
/// 
/// @param {Number}                $target         []       `[required]` <br>
///                                                         Target pixel value
///                                                                              
/// @param {Number}                $context        []       `[required]` <br>
///                                                         Context (root!) pixel size
///                                                                              
///
/// @return {Number} The `px` value converted to `rem`
///
@function rem($target, $context: $default-conversion-context) {
    @return ($target / $context) * 1rem;
}

///
/// Converts one value or a list of values to `rem` with `px`-fallback. This mixin is primarily used internally.
/// 
/// @param {String}                         $property           []                      `[required]` <br>
///                                                                                     CSS-Property which values will be converted to rem.
///                                                     
/// @param {Number | List(Number)}          $values             []                      `[required]` <br>
///                                                                                     Single value or a list of values
///                                                     
/// @param {Boolean}                        $important          [false]                 `[optional]` <br>
///                                                                                     Append `!important` to the converted value(s).
///                                                     
/// @param {Boolean}                        $use-rem            [$use-rem-on-default]   `[optional]` <br>
///                                                                                     Toggle `em`-output.   
///                                                                                     

@mixin rem($property, $values, $important: false, $use-rem: $use-rem-on-default) {
    $imp: if($important, !important, '');

    $value-list-rem: ();
    $value-list-px: ();

    @for $i from 1 through length($values) {

        $value: nth($values, $i);
        $rem-value: 0;
        $px-value : 0;

        @if ($value != 0 and is-number($value)) or $value == auto {


            @if($value == auto or is-percent($value) or unitless($value)) {
                $rem-value: $value;
                $px-value : $value;

            } @else {
                $rem-value: if(is-rem($value), $value, if(is-px($value), rem($value), $value));
                $px-value : if(is-px($value), $value, if(is-rem($value), px($value), $value));
            }

        }

        $value-list-rem: append($value-list-rem, $rem-value);
        $value-list-px : append($value-list-px, $px-value);
    }

    @if (length($value-list-px) > 1) {

        // Liste von Werten

        #{$property}: $value-list-px #{$imp};

        @if ($use-rem) {
            #{$property}: $value-list-rem #{$imp};
        }

    } @else {

        // nur ein Wert, keine Liste

        #{$property}: $value-list-px #{$imp};

        @if ($use-rem and nth($value-list-px, 1) != nth($value-list-rem, 1)) {
            #{$property}: $value-list-rem #{$imp};
        }
    }

}

then the mixin that utilizes the rem mixin above

///
/// Mixin to convert `line-height` to `rem` with `px`-fallback.
///
/// @param {Number} $height [] `[required]` <br> Value that will be converted to `rem`.
/// 
/// @param {Boolean} $important [false] `[optional]` <br> append `!important` to the output.
///
/// @param {Boolean} $use-rem [$use-rem-on-default] `[optional]` <br> Toggle `em`-output.
/// 
/// @example scss - Usage with `px` and `important`
/// .selector {
///     @include line-height(20px, important: true);
/// }
/// 
/// // ## Output ## 
/// 
///  
/// .selector {
///     line-height: 20px !important;
///     line-height: 1.25rem !important;
/// }
/// 
/// @require {mixin} rem 
///
@mixin line-height($height, $important: false, $use-rem: $use-rem-on-default) {
    @include rem(line-height, $height, $important);
}

The SassDoc output then:

Requires

[mixin] height
[function] rem

Should'nt the SassDoc output link to the mixin that is utilized? Maybe it's because the mixin rem utilizes the functionrem. I've gotten a little confused about that.

[valeriangalliat]

Okay I get it, the autofill was correct (outputing { type: 'mixin', name: 'rem' }), but the item resolution was wrong, because it filtered on the name only.

So it takes the first item with this name, regardless the type; in your example, the function precedes the mixin, while in my attempt to reproduce, the mixin was first.

Fixed with SassDoc 2.1.6!

[PixelZombie]

Nice, thank you! Maybe I should've put the correct order of the function / mixin in the first place ;-)