@@ -13,60 +13,34 @@ object Magnolia {
1313
1414 /** derives a generic typeclass instance for the type `T`
1515 *
16- * This is a macro definition method which should be bound to a method defined inside a Magnolia
17- * generic derivation object, that is, one which defines the methods `join`, `split` and
18- * the type constructor, `Typeclass[_]`. This will typically look like,
19- * <pre>
20- * object Derivation {
21- * // other definitions
22- * implicit def gen[T]: Typeclass[T] = Magnolia.gen[T]
23- * }
24- * </pre>
25- * which would support automatic derivation of typeclass instances by calling
26- * `Derivation.gen[T]` or with `implicitly[Typeclass[T]]`, if the implicit method is imported
27- * into the current scope.
16+ * This is a macro definition method which should be bound to a method defined inside a Magnolia generic derivation object, that is, one
17+ * which defines the methods `join`, `split` and the type constructor, `Typeclass[_]`. This will typically look like, <pre> object
18+ * Derivation { // other definitions implicit def gen[T]: Typeclass[T] = Magnolia.gen[T] } </pre> which would support automatic
19+ * derivation of typeclass instances by calling `Derivation.gen[T]` or with `implicitly[Typeclass[T]]`, if the implicit method is
20+ * imported into the current scope.
2821 *
29- * If the `gen` is not `implicit`, semi-auto derivation is used instead, whereby implicits will
30- * not be generated outside of this ADT.
22+ * If the `gen` is not `implicit`, semi-auto derivation is used instead, whereby implicits will not be generated outside of this ADT.
3123 *
32- * The definition expects a type constructor called `Typeclass`, taking one *-kinded type
33- * parameter to be defined on the same object as a means of determining how the typeclass should
34- * be genericized. While this may be obvious for typeclasses like `Show[T]` which take only a
35- * single type parameter, Magnolia can also derive typeclass instances for types such as
36- * `Decoder[Format, Type]` which would typically fix the `Format` parameter while varying the
37- * `Type` parameter.
24+ * The definition expects a type constructor called `Typeclass`, taking one *-kinded type parameter to be defined on the same object as a
25+ * means of determining how the typeclass should be genericized. While this may be obvious for typeclasses like `Show[T]` which take only
26+ * a single type parameter, Magnolia can also derive typeclass instances for types such as `Decoder[Format, Type]` which would typically
27+ * fix the `Format` parameter while varying the `Type` parameter.
3828 *
39- * While there is no "interface" for a derivation, in the object-oriented sense, the Magnolia
40- * macro expects to be able to call certain methods on the object within which it is bound to a
41- * method.
29+ * While there is no "interface" for a derivation, in the object-oriented sense, the Magnolia macro expects to be able to call certain
30+ * methods on the object within which it is bound to a method.
4231 *
43- * Specifically, for deriving case classes (product types), the macro will attempt to call the
44- * `join` method with an instance of [[CaseClass ]], like so,
45- * <pre>
46- * <derivation>.join(<caseClass>): Typeclass[T]
47- * </pre>
48- * That is to say, the macro expects there to exist a method called `join` on the derivation
49- * object, which may be called with the code above, and for it to return a type which conforms
50- * to the type `Typeclass[T]`. The implementation of `join` will therefore typically look
51- * like this,
52- * <pre>
53- * def join[T](caseClass: CaseClass[Typeclass, T]): Typeclass[T] = ...
54- * </pre>
55- * however, there is the flexibility to provide additional type parameters or additional
56- * implicit parameters to the definition, provided these do not affect its ability to be invoked
57- * as described above.
32+ * Specifically, for deriving case classes (product types), the macro will attempt to call the `join` method with an instance of
33+ * [[CaseClass ]], like so, <pre> <derivation>.join(<caseClass>): Typeclass[T] </pre> That is to say, the macro expects there
34+ * to exist a method called `join` on the derivation object, which may be called with the code above, and for it to return a type which
35+ * conforms to the type `Typeclass[T]`. The implementation of `join` will therefore typically look like this, <pre> def
36+ * join[T](caseClass: CaseClass[Typeclass, T]): Typeclass[T] = ... </pre> however, there is the flexibility to provide additional type
37+ * parameters or additional implicit parameters to the definition, provided these do not affect its ability to be invoked as described
38+ * above.
5839 *
59- * Likewise, for deriving sealed traits (coproduct or sum types), the macro will attempt to call
60- * the `split` method with an instance of [[SealedTrait ]], like so,
61- * <pre>
62- * <derivation>.split(<sealedTrait>): Typeclass[T]
63- * </pre>
64- * so a definition such as,
65- * <pre>
66- * def split[T](sealedTrait: SealedTrait[Typeclass, T]): Typeclass[T] = ...
67- * </pre>
68- * will suffice, however the qualifications regarding additional type parameters and implicit
69- * parameters apply equally to `split` as to `join`.
40+ * Likewise, for deriving sealed traits (coproduct or sum types), the macro will attempt to call the `split` method with an instance of
41+ * [[SealedTrait ]], like so, <pre> <derivation>.split(<sealedTrait>): Typeclass[T] </pre> so a definition such as, <pre> def
42+ * split[T](sealedTrait: SealedTrait[Typeclass, T]): Typeclass[T] = ... </pre> will suffice, however the qualifications regarding
43+ * additional type parameters and implicit parameters apply equally to `split` as to `join`.
7044 */
7145 def gen [T : c.WeakTypeTag ](c : whitebox.Context ): c.Tree = Stack .withContext(c) { (stack, depth) =>
7246 import c .internal ._
@@ -128,7 +102,7 @@ object Magnolia {
128102 .flatMap(_.tree.children.tail.collectFirst {
129103 case Literal (Constant (arg : String )) => arg
130104 case tree if DebugTpe .companion.decls.exists(_ == tree.symbol) => " " // Default constructor, i.e. @debug or @debug()
131- case other => error(s " Invalid argument $other in @debug annotation. Only string literals or empty constructor supported " )
105+ case other => error(s " Invalid argument $other in @debug annotation. Only string literals or empty constructor supported " )
132106 })
133107
134108 object DeferredRef {
@@ -143,21 +117,22 @@ object Magnolia {
143117 }
144118 }
145119
146- /** Returns the chain of owners of `symbol` up to the root package in reverse order.
147- * The owner of a symbol is the enclosing package/trait/class/object/method/val/var where it is defined.
148- * More efficient than [[ ownerChainOf ]] because it does not materialize the owner chain.
120+ /** Returns the chain of owners of `symbol` up to the root package in reverse order. The owner of a symbol is the enclosing
121+ * package/trait/class/object/method/val/var where it is defined. More efficient than [[ ownerChainOf ]] because it does not materialize
122+ * the owner chain.
149123 */
150124 def reverseOwnerChainOf (symbol : Symbol ): Iterator [Symbol ] =
151125 Iterator .iterate(symbol)(_.owner).takeWhile(owner => owner != null && owner != NoSymbol )
152126
153127 /** Returns the chain of owners of `symbol` up to the root package.
154- * @see [[reverseOwnerChainOf ]]
128+ * @see
129+ * [[reverseOwnerChainOf ]]
155130 */
156131 def ownerChainOf (symbol : Symbol ): Iterator [Symbol ] =
157132 reverseOwnerChainOf(symbol).toVector.reverseIterator
158133
159- /** Returns a type-checked reference to the companion object of `clazz` if any.
160- * Unlike `clazz.companion` works also for local classes nested in methods/vals/vars.
134+ /** Returns a type-checked reference to the companion object of `clazz` if any. Unlike `clazz.companion` works also for local classes
135+ * nested in methods/vals/vars.
161136 */
162137 def companionOf (clazz : ClassSymbol ): Option [Tree ] = {
163138 val fastCompanion = clazz.companion
@@ -703,8 +678,8 @@ object Magnolia {
703678
704679 /** constructs a new [[Param ]] instance
705680 *
706- * This method is intended to be called only from code generated by the Magnolia macro, and
707- * should not be called directly from users' code.
681+ * This method is intended to be called only from code generated by the Magnolia macro, and should not be called directly from users'
682+ * code.
708683 */
709684 private [Magnolia ] def param [Tc [_], T , P ](
710685 name : String ,
0 commit comments