Add more information to reflection guide #2005
Conversation
| @@ -75,6 +98,47 @@ def g[T: Type](using Quotes) = | |||
| ... | |||
| ``` | |||
|
|
|||
| ## Symbols | |||
There was a problem hiding this comment.
A thing worth checking is whether the flavor of Markdown used for the docs supports heading IDs. In my experience, adding is a good way of future-proofing internal links, in case a title changes.
There was a problem hiding this comment.
docs.scala-lang uses kramdown. I ran jekyll serve and the internal link seems to work
Co-authored-by: Maxime Kjaer <maxime.kjaer@gmail.com>
Co-authored-by: Maxime Kjaer <maxime.kjaer@gmail.com>
|
|
||
| For example [`TypeBounds`](https://dotty.epfl.ch/api/scala/quoted/Quotes$reflectModule.html#TypeBounds-0), a subtype of `TypeRepr`, represents a type tree of the form `T >: L <: U`: a type `T` which is a super type of `L` |
There was a problem hiding this comment.
| For example [`TypeBounds`](https://dotty.epfl.ch/api/scala/quoted/Quotes$reflectModule.html#TypeBounds-0), a subtype of `TypeRepr`, represents a type tree of the form `T >: L <: U`: a type `T` which is a super type of `L` | |
| For example [`TypeBounds`](https://dotty.epfl.ch/api/scala/quoted/Quotes$reflectModule.html#TypeBounds-0), a subtype of `TypeRepr`, represents a type of the form `T >: L <: U`: a type `T` which is a super type of `L` |
There was a problem hiding this comment.
I think it might be confusing to call TypeRepr when we have TypeTree around
| is not used, then the `tree` of the symbol will not be available. Symbols originated from | ||
| Java code do not have an associated `tree`. | ||
|
|
||
| ## Suggestion and anti-patterns |
There was a problem hiding this comment.
Those should be moved to https://docs.scala-lang.org/scala3/guides/macros/best-practices.html. There we can expand a bit each point and add some examples if possible.
We could leave a link to that page here.
There was a problem hiding this comment.
I moved a few points to best-practices.md and provided small examples
Co-authored-by: Nicolas Stucki <nicolas.stucki@gmail.com>
Co-authored-by: Nicolas Stucki <nicolas.stucki@gmail.com>
Co-authored-by: Nicolas Stucki <nicolas.stucki@gmail.com>
Co-authored-by: Nicolas Stucki <nicolas.stucki@gmail.com>
Co-authored-by: Nicolas Stucki <nicolas.stucki@gmail.com>
…lang into reflection-guide
|
|
||
| - `tpe.typeSymbol` returns the symbol of the type represented by `TypeRepr`. The recommended way to obtain a `Symbol` given a `Type[T]` is `TypeRepr.of[T].typeSymbol` | ||
| - For a singleton type, `tpe.termSymbol` returns the symbol of the underlying object or value. | ||
| - `tpe.memberType(symbol)` returns the `TypeRepr` of the provided symbol |
There was a problem hiding this comment.
Maybe give an example? (That could be added later in a separate PR)
Something that would be useful IMHO would be to show a concrete example of what this would expand to (e.g., how do I construct a tree for the type expression Foo#Bar (for some type Foo that has a type member Bar).
| @@ -40,14 +40,14 @@ This will import all the types and modules (with extension methods) of the API. | |||
|
|
|||
| ## How to navigate the API | |||
|
|
|||
| The full imported API can be found in the [API documentation for `scala.quoted.Quotes.reflectModule`][reflection doc]. | |||
| The full API can be found in the [API documentation for `scala.quoted.Quotes.reflectModule`][reflection doc]. | |||
| Unfortunately, at this stage, this automatically generated documentation is not very easy to navigate. | |||
|
|
|||
| The most important element on the page is the hierarchy tree which provides a synthetic overview of the subtyping relationships of | |||
| the types in the API. For each type `Foo` in the tree: | |||
There was a problem hiding this comment.
It might not be fully clear that Foo is a metavariable, we could also use something like <TYPE>Methods. But if you think that is not necessary, then I am also ok with how it is.
There was a problem hiding this comment.
But this can also be addressed in a separate PR. To not block any longer, I am going to accept and merge it as is.
This PR adds some information that I wished had been documented when I started to use the API.
Most of the elements were discussed with @liufengyun and @MaximeKjaer