Документирование Scala 2.10 макросов

Я начну с примера. Здесь эквивалент List.fill для кортежей как макроса в Scala 2.10:

import scala.language.experimental.macros
import scala.reflect.macros.Context

object TupleExample {
  def fill[A](arity: Int)(a: A): Product = macro fill_impl[A]

  def fill_impl[A](c: Context)(arity: c.Expr[Int])(a: c.Expr[A]) = {
    import c.universe._

    arity.tree match {
      case Literal(Constant(n: Int)) if n < 23 => c.Expr(
        Apply(
          Select(Ident("Tuple" + n.toString), "apply"),
          List.fill(n)(a.tree)
        )
      )
      case _ => c.abort(
        c.enclosingPosition,
        "Desired arity must be a compile-time constant less than 23!"
      )
    }
  }
}

Мы можем использовать этот метод следующим образом:

scala> TupleExample.fill(3)("hello")
res0: (String, String, String) = (hello,hello,hello)

Этот парень - странная птица в нескольких отношениях. Во-первых, аргумент arity должен быть буквальным целым числом, так как мы должны использовать его во время компиляции. В предыдущих версиях Scala не было способа (насколько я знаю) для метода даже сказать, был ли один из его аргументов литералом компиляции или нет.

Во-вторых, возвращаемый тип Product является ложью - статический тип возврата будет включать в себя определенный тип и тип элемента, определяемый аргументами, как показано выше.

Итак, как я могу документировать эту вещь? Я не ожидал поддержки Scaladoc на данный момент, но я хотел бы иметь смысл соглашений или лучших практик (за исключением того, что я уверен, что сообщения об ошибках во время компиляции ясны), которые заставили бы работать в макро-метод - с его потенциально странные требования - менее удивительные для пользователей библиотеки Scala 2.10.

Самые зрелые демонстрации новой макросистемы (например, ScalaMock, Slick, остальные, перечисленные здесь) по-прежнему относительно не документированы на уровне метода. Будут оценены любые примеры или указатели, в том числе и другие языки с похожими макросистемами.

Ответ 1