add documentation for compiler plugin #4658
Conversation
| normal type checking. This is a nice feature for doing research, but for | ||
| production usage, a predictable and consistent type checker is more important. | ||
|
|
||
| For experiments and researches that depend on analyzer plugins in Scalac, |
| your domain-specific language. Research plugins are only enabled for nightly or | ||
| snaphot releases of Dotty. | ||
|
|
||
| The common plugins that add a new phase to the compiler pipeline are called |
There was a problem hiding this comment.
Only one phase?
The common plugins that add new phases ...
| ``` | ||
|
|
||
| The above is a change from Scalac, which depends on an XML file | ||
| `scalac-plugin.xml`. Since SBT 1.1.5, SBT also supports Dotty compiler plugins: |
There was a problem hiding this comment.
Starting with 1.1.5, sbt also...
| @@ -10,13 +10,13 @@ import Symbols.Symbol | |||
| import Constants.Constant | |||
| import StdNames._ | |||
|
|
|||
| class DivideZero extends MiniPhase with ResearchPlugin { | |||
| class DivideZero extends PluginPhase with ResearchPlugin { | |||
There was a problem hiding this comment.
Since the CI only run the sbt scripted tests on nightlies, can you confirm that you ran this test locally
There was a problem hiding this comment.
This test is a neg test, not a scripted test. I just checked it works locally. I confused my self, for research plugins, we don't need the phases to be PluginPhase.
|
|
||
| For experiments and researches that rely on analyzer plugins in Scalac, | ||
| _research plugin_ can be used for the same purpose in Dotty. Research plugins | ||
| are more powerful than Scalac analyzers as it enables plugin authors to |
There was a problem hiding this comment.
"Than Scalac analyzer plugins"
|
|
||
| For experiments and researches that rely on analyzer plugins in Scalac, | ||
| _research plugin_ can be used for the same purpose in Dotty. Research plugins | ||
| are more powerful than Scalac analyzers as it enables plugin authors to |
| your domain-specific language. Research plugins are only enabled for nightly or | ||
| snaphot releases of Dotty. | ||
|
|
||
| The common plugins that add new phases to the compiler pipeline are called |
There was a problem hiding this comment.
I'd switch the order of these 2 paragraphs, let's describe first the common case?
There was a problem hiding this comment.
I agree, but it seems the 2nd paragraph follows more naturally after the 1st paragraph. If we switch the 3rd and the 2nd, we have a problem between 1st and 3rd.
| _standard plugins_ in Dotty. In terms of features, they are similar to | ||
| Scalac plugins, despite minor changes in the API. | ||
|
|
||
| ## Physical Interface |
There was a problem hiding this comment.
Physical interface reads like a USB port, I'd call this section "Using compiler plugins" and have a separate subsection for the command line and for sbt.
There was a problem hiding this comment.
Maybe we can call it plugin artifact interface?
|
|
||
| ``` | ||
| pluginClass=dividezero.DivideZero | ||
| ``` |
There was a problem hiding this comment.
Is this relevant to this section? Maybe this should go in a section called "Writing compiler plugins"?
| addCompilerPlugin("org.divbyzero" % "divbyzero" % "1.0") | ||
| ``` | ||
|
|
||
| ## Standard Plugin |
There was a problem hiding this comment.
Maybe call this "Writing your first plugin", and move the content of plugin.properties here?
There was a problem hiding this comment.
That can be more friendly, but I feel the tutorial-like style doesn't fit the documentation style of other pages.
allanrenucci
force-pushed
the
plugin-doc
branch
2 times, most recently
from
6aebe80 to
eafa497
Compare
|
Otherwise, LGTM. Thanks a lot @allanrenucci @Duhemm ! |
add documentation for compiler plugin