diff options
| -rw-r--r-- | coreMacros/src/main/scala/chisel3/SourceInfoDoc.scala | 42 |
1 files changed, 42 insertions, 0 deletions
diff --git a/coreMacros/src/main/scala/chisel3/SourceInfoDoc.scala b/coreMacros/src/main/scala/chisel3/SourceInfoDoc.scala new file mode 100644 index 00000000..ad320d5d --- /dev/null +++ b/coreMacros/src/main/scala/chisel3/SourceInfoDoc.scala @@ -0,0 +1,42 @@ +// See LICENSE for license details + +package chisel3 + +/** Provides ScalaDoc information for "hidden" `do_*` methods + * + * Mix this into classes/objects that have `do_*` methods to get access to the shared `SourceInfoTransformMacro` + * ScalaDoc group and the lengthy `groupdesc` below. + * + * @groupdesc SourceInfoTransformMacro + * + * <p> + * '''These internal methods are not part of the public-facing API!''' + * <br> + * <br> + * + * The equivalent public-facing methods do not have the `do_` prefix or have the same name. Use and look at the + * documentation for those. If you want left shift, use `<<`, not `do_<<`. If you want comversion to a [[Seq]] of + * [[Bool]]s look at the `toBools` above, not the one below. Users can safely ignore every method in this group! + * <br> + * <br> + * + * 🐉🐉🐉 '''Here be dragons...''' 🐉🐉🐉 + * <br> + * <br> + * + * These `do_X` methods are used to enable both implicit passing of [[SourceInfo]] and + * [[chisel3.core.CompileOptions]] while also supporting chained apply methods. In effect all "normal" methods that + * you, as a user, will use in your designs, are converted to their "hidden", `do_*`, via macro transformations. + * Without using macros here, only one of the above wanted behaviors is allowed (implicit passing and chained + * applies)---the compiler interprets a chained apply as an explicit 'implicit' argument and will throw type errors. + * <br> + * <br> + * + * The "normal", public-facing methods then take no [[SourceInfo]]. However, a macro transforms this public-facing + * method into a call to an internal, hidden `do_*` that takes an explicit [[SourceInfo]] by inserting an + * `implicitly[SourceInfo]` as the explicit argument. + * </p> + * + * @groupprio SourceInfoTransformMacro 1001 + */ +trait SourceInfoDoc |