New scaladoc model

[xeno-by]

How did you guys decide to proceed with the new scaladoc? Are you going to be building something completely from scratch? Are you going to depend on scala.reflect? Do you mind depending on scala.meta?

[cvogt]

@xeno-by I had a chat with @MasseGuillaume on gitter. He had started building a doc focused AST and transforms meta trees into these. We also started such an AST as you can see in this PR. So we concluded we should cooperate on that AST. @kolowheel would work on the AST and generating output for different backends from it. @MasseGuillaume would help collaborate/overseeing his work on the AST and continue building his tree translator from scala meta to the doc asts. @kolowheel will either create doc asts by hand for testing purposes, or write a translator from scaladoc 2.11 for it. @MasseGuillaume advises against a scaladoc sourced translator, because he said it would be basically replicating lots of effort from meta. I can also see @kolowheel use and low priority contribute to a @MasseGuillaume's translator, but we have to try hard not to block him if that breaks.

WDYT?

[xeno-by]

How many nodes are you going to need for scaladoc? Is it just definitions and their signatures, or there might be more, e.g. patterns, types, etc?

[cvogt]

@xeno-by I don't know, @kolowheel will have to see as he goes along.

[xeno-by]

What if you could use quasiquotes that would shield you from API changes? Would that be a sufficient stability guarantee for your project?

The thing is that it takes a lot of effort to have an AST that has even the basic conveniences like non-desugared view of the world, parents, positions, etc. I'm afraid that you might be reimplementing some stuff that we painstakingly went through in scala.meta.

[cvogt]

I am doubtful that quasi quotes provide enough. Writing quasi quote macros for 2.10 paradise and 2.11 still requires dealing with compatibility. Also not sure how well quasi quotes would do in a doc context.

[xeno-by]

Also, from what I see, you're not only interested in syntax (methods like override def getKnownSubclasses(id: ID): Seq[ID] = ???). This will be a reimplementation of a part of scala.meta that does communication with scala.reflect to datamine and present semantic information (that's a lot of work as well).

[MasseGuillaume]

You guys @xeno-by @cvogt should start a google hangout. :P

[xeno-by]

Yeah, we probably should. Chris, are you available?

[cvogt]

Summary of @xeno-by's and my hangout: doc directed trees seem to be the way to go.

[MasseGuillaume]

@cvogt define doc directed trees

[xeno-by]

The model that can be used to render the docs without having any compiler/meta/whatever else at hand. E.g. you can serialize into json, then load in javascript on a random machine disconnected from the rest of the world and you should still be able to render it.

[cvogt]

a data structure, from which documentation can be generated easily without consulting a compiler. E.g. finding all subclasses should be represented as data rather than using a typechecker. But generating an index could be allowed to be a method, which traverses the doc directed tress. I think we are all on the same page and that's what you were heading for as well.

[clhodapp]

I have a couple things i could bring up, but I think I'll just say LGTM so we can merge this thing.

[cvogt]

LGTM, let's merge this!