Enums/ Документация с LESS Mixins

Question

Я создаю набор миксов LESS с Visual Studio/Web Essentials.

Можно ли написать документацию типа XML для миксов LESS? Или, может быть, есть enum для ограничения вводимых параметров?

Например, с этим миксином:

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

Было бы неплохо иметь некоторую документацию, которая описывает три возможных значения, как при создании обычного CSS-селектора для background-clip -

Answer 1

Список допустимых значений Enum

Это будет обработано параметрическим вызовом mixin, например так:

.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;
}

Это позволяет передать только четыре значения, заданные для его активации. Итак, это:

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

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

Получил бы этот вывод (игнорируя второй вызов, потому что он не действителен):

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

Комментируемая обратная связь

Если требуется получить обратную связь с пользователем, то второй параметрический миксин может предложить это через комментарий.

ВАРИАНТ 1 - чистый комментарий

.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
  */
}

Тогда приведенный выше тестовый пример будет иметь такой дополнительный вывод:

.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
  */
}

ВАРИАНТ 2 включает в себя фиктивное значение свойства, чтобы показать, что неправильное @value вход был:

.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
  */
}

Который выводит этот дополнительный тестовый пример 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
      */
}

Браузеры будут игнорировать непризнанное "свойство" invalid-background-clip-input-equals, но он будет предупреждать одного просмотра скомпилированного CSS, что недействительным было переданное значение.

ВАРИАНТ 3 включает в себя фиктивный (то есть неопределенный) миксин, который может вызвать ошибку компиляции (разные компиляторы могут по-разному обрабатывать неопределенные миксины):

.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();
}

Который выводит в этот компилятор эту информацию:

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

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

Это может быть способом "заставить" менее программиста ввести правильное значение, выдав ошибку. Обратите внимание, что в этом случае фактический неопределенный миксин, выдающий ошибку, является .background-clip-undefined()тем не менее, этот компилятор фактически предоставляет информацию о вызове .background-clip(something) что действительно является ошибкой.

Можно комбинировать варианты 2 и 3, чтобы, если компилятор не выдавал ошибку, была видна, по крайней мере, обратная связь с комментарием.