Improve documentation of "always-multi-line" in at-rule-name-newline-after

[davegomez]

Describe the issue. Is it a bug or a feature request (new rule, new option, etc.)?

I think there's a bug the rule, it shows an error even when the snippet complies with it. It doesn't happen with all the @mixin at-rules but only with these specially long and deeply nested rules that you can find in the Flexbox Grid SCSS code.

Which rule, if any, is this issue related to?

at-rule-name-newline-after

What CSS is needed to reproduce this issue?

@mixin columns(
  $selector: $column-selector,
  $properties: $column-properties,
  $columns: $column-count,
  $queries: $queries
) {
  @each $size in $sizes {
    @include queries($size, $queries) {
      @for $i from 0 through $columns {
        @if ($i == 0) {
          #{$selector}#{$block-delimiter}#{$size} {
            @content;

            @include autoWidth();
          }
        }

        @else {
          #{$selector}#{$block-delimiter}#{$size}#{$modifier-delimiter}#{$i} {
            @content;

            @each $prop in $properties {
              @include percentWidth($prop, $columns, $i);
            }
          }
        }
      }
    }
  }
}

What stylelint configuration is needed to reproduce this issue?

{
  "rules": {
    "at-rule-name-newline-after": "always-multi-line"
  }
}

Which version of stylelint are you using?

7.7.1

How are you running stylelint: CLI, PostCSS plugin, Node API?

CLI with stylelint scss/**/*.scss --syntax scss and IDE/Editor plugins

Does your issue relate to non-standard syntax (e.g. SCSS, nesting, etc.)?

Yes, it's related to SCSS syntax.

What did you expect to happen?

No errors to be flagged.

What actually happened (e.g. what warnings or errors you are getting)?

The following errors were flagged:

scss/_fg-grid.scss
 118:6  ✖  Expected newline after at-rule name "@mixin"   at-rule-name-newline-after

[hudochenkov]

The rule works like expected.

@mixin columns(
  $selector: $column-selector,
  $properties: $column-properties,
  $columns: $column-count,
  $queries: $queries
) {}

After at-rule name mixin and before at-rule's block {} there are multiple lines. You can check examples in docs.

I think we should improve description for this rule. It's clear from examples what this rule checks, but it's not — from a text.

[jeddy3]

The rule works like expected.

Agreed.

I think we should improve description for this rule.

Agreed. Currently, the docs say:

There must always be a newline after at-rule names in multiline-line at-rule blocks.

It's the "at-rule blocks" bit that is off.

Any idea what the bit between at-rule name and the opening brace is called?

[hudochenkov]

Any idea what the bit between at-rule name and the opening brace is called?

For @media it's called media query list. PostCSS AST calls it params. I propose to use “parameters list”.

[jeddy3]

I propose to use “parameters list”.

SGTM. It's called group rule body for conditional group rules - so going with something generic like "parameters list" sounds good to me.

[davidtheclark]

How about just "parameters"? No need for the word "list", right?

…

On Jan 21, 2017, at 5:36 AM, Richard Hallows ***@***.***> wrote: I propose to use “parameters list”. SGTM. It's called group rule body for conditional group rules - so going with something generic like "parameters list" sounds good to me. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or mute the thread.

[jeddy3]

Done in #2304