Enums/Documentation with LESS Mixins

Question

I am creating a set of LESS mixins with Visual Studio/Web Essentials.

Is it possible to write XML-type documentation for LESS mixins? Or perhaps have an enum to limit the parameters that are input?

For instance, with this mixin:

.background-clip(@value)
{
    -webkit-background-clip: @value;
       -moz-background-clip: @value;
            background-clip: @value;
}

It would be nice to have some documentation that describes the three possible values, just like when you are creating a normal CSS selector for background-clip -

Heptane

Answer 1

An "Enum" List of Accepted Values

This would be handled through a parametric mixin call, like this:

.background-clip(@value) when (@value = border-box),
                              (@value = padding-box),
                              (@value = content-box),
                              (@value = inherit)
{
    -webkit-background-clip: @value;
       -moz-background-clip: @value;
            background-clip: @value;
}

This only allows the four values given to be passed in order for it to activate. So this:

.test1 {
  .background-clip(border-box);
}

.test2 {
  .background-clip(something);
}

Would yield this output (ignoring the second call because it is not valid):

.test1 {
  -webkit-background-clip: border-box;
  -moz-background-clip: border-box;
  background-clip: border-box;
}

Commented Feedback

If feedback to the user was wanted, then a second parametric mixin could offer that through a comment.

OPTION 1 is pure comment

.background-clip(@value) when not (@value = border-box) and
                              not (@value = padding-box) and
                              not (@value = content-box) and
                              not (@value = inherit)
{
  /* WARNING - INVALID INPUT
     CSS output for backbround-clip property given in
     LESS .background-clip() call has been suppressed
     due to invalid input.

     VALID INPUT is one of:
       border-box
       padding-box
       content-box
       inherit
  */
}

Then the above test case would have this additional output:

.test2 {
  /* WARNING - INVALID INPUT
     CSS output for backbround-clip property given in
     LESS .background-clip() call has been suppressed
     due to invalid input.

     VALID INPUT is one of:
       border-box
       padding-box
       content-box
       inherit
  */
}

OPTION 2 includes a bogus property value to show what the improper @value input was:

.background-clip(@value) when not (@value = border-box) and
                              not (@value = padding-box) and
                              not (@value = content-box) and
                              not (@value = inherit)
{
  /* WARNING - INVALID INPUT */
  invalid-background-clip-input-equals: @value;
  /* CSS output for backbround-clip property given in
     LESS .background-clip() call has been suppressed
     due to invalid input.

     VALID INPUT is one of:
       border-box
       padding-box
       content-box
       inherit
  */
}

Which outputs this additional test case CSS:

.test2 {
  /* WARNING - INVALID INPUT */
  invalid-background-clip-input-equals: something;
  /* CSS output for backbround-clip property given in
         LESS .background-clip() call has been suppressed
         due to invalid input.

         VALID INPUT is one of:
           border-box
           padding-box
           content-box
           inherit
      */
}

Browsers would ignore the unrecognized "property" of invalid-background-clip-input-equals, but it would alert one viewing the compiled css what invalid the value passed was.

OPTION 3 includes a bogus (i.e. undefined) mixin to potentially force a compilation error (different compilers might handle undefined mixins differently):

.background-clip(@value) when not (@value = border-box) and
                              not (@value = padding-box) and
                              not (@value = content-box) and
                              not (@value = inherit)
{
   .background-clip-undefined();
}

Which outputs in this compiler this information:

SyntaxError: .background-clip-undefined is undefined on line 24, column 3:

23 .test2 {
24   .background-clip(something);
25 }

This may be a way to "force" the less programmer to input a valid value by throwing an error. Note how in this case the actual undefined mixin giving the error is the .background-clip-undefined(), yet this compiler is actually providing the "calling" information .background-clip(something) which is really what the error is.

One could combine options 2 and 3 so that if an error is not thrown by a compiler, at least the comment feedback is visible.

Orthohydrogen

Perfect! Thanks for such a great response! – Heptane

ScottS this is a nice answer but would it be possible to make the less compilation fail instead of ignoring the bad mixin usage??? – Graner

@SebastienLorber: Updated with an Option 3 that may work to do what you requested (though it may vary by compiler what the effect would be and what information would be returned). – Orthohydrogen

ScottS that is probably working :) however this is a bit hacky and needs too much boilerplate by creating when not clauses to be useful to me. I've created this issue and will probably create a less plugin soon: github.com/less/less.js/issues/2747#issuecomment-161789791 – Graner