Generate or retain scaladoc

[DavidDudson]

Mentioned it gitter multiple times.

We will need to either pull in scalafix and/or handle it with a scalameta/contrib patch for transforming trees while retaining comments.

[olafurpg]

This is problem is still an active area of research, see https://github.com/camfort/reprinter. It's far from solved in scalafix with Patch.

I believe the state-of-the art in this space is what I describe here https://github.com/scalameta/scalameta/issues/1137#issuecomment-338434998 I've been meaning to either move the scala-syntax repo to scalafmt or scalameta. This would allow users to write Tree.transform and where applicable explicitly copy over comments where important tree nodes are deconstructed into other trees.

[DavidDudson]

@olafurpg I have a rough idea that should work for scaladoc comments only...

The new backend uses a tree of "Contexts", it's almost done and should be this weekend.

The GeneratorInputContext contains input tree, generators to apply, soon the semantic api etc.

This get's turned into a GeneratorOutputContext which contains the input + the result.

The plan

1. Get the ADT of the the scaladoc for each Defn/Decl in the tree when converting from Tree -> GeneratorInputContext and add it as a field GeneratorInputContext
2. Allow the user to update the scaladoc for a given Defn/Decl and enable/disable scaladoc preservation.
3. Have a Show[Syntax] instance for GeneratorOutputContext which can handle doc comments.

Notes:

• This definitely would not be easy, the retaining of doc is easy, but generating the syntax would be harder.
• This would only work for the annotee, or untransformed tree's, not subtrees that have been transformed, although its possible we might be able to tweak it to be slightly more general.