yarhrn / new-scaladoc Goto Github PK

e.g.

trait Foo{
  type Z // abstract type
  type X = Option[Map[Int, String]] // type alias
}

  def processPackage(pack: Package): String = {
    val grouped: Map[String, Seq[DocElement]] = pack.elements.groupBy {
      case e: ClassDoc => "classes"
      case e: ObjectDoc => "objects"
      case e: TraitDoc => "traits"
      case e: DocElement => "nvm"
    }
    processObjects(grouped("objects").map(_.asInstanceOf[ObjectDoc]))

->

val objects = pack.elements.collect { case o: ObjectDoc => o }
processObjects(objects)

can be in the readme, just an overview about the ideas behind this project, so that someone else can understand the context and how we decided to solve thus problem

• check scaladoc's parser and how hard it is to port it
• check scala meta on how to get the doc code
• make a plan how to integrate it

This file needs to be turned into a test. https://github.com/kolowheel/new-scaladoc/blob/74918a4cddabb1bc2aa8322c54fef53026e35364/src/main/scala/Main.scala You already got ScalaTest in your dependencies. Use it :). Also, please just use the FunSuite with assert calls, no funny dsls (the test framework are meaning well, but doing harm there in my eyes).

Foo[T,Q] and T with Q

there are some orphaned calls and in general let's avoid stripMargin if in any way possible, it just make the code harder to mangle.

An index like http://www.scala-lang.org/api/2.11.5/index.html#index.index-a, where all classes and methods etc are listed. Hopefully a better one, that is structured by type, method, term (aka value or object), etc. This may need some case classes, which aren't prefilled in a model, but computed from a model and can be used by a backend to produce a visual representation of the index.

Write frontend that goes from Scala source code to new-scaladoc trees. Wrap it all up, so you can go straight from source to PDF docs all the way.

I would like to see this project help the efforts in scala meta and meta doc if in any way possible. One is to keep the trees as similar as possible, so that it is easy to take over code between the projects or interop as libraries.

It seems to me that the strategy should be that we replicate meta's trees in their current state, but add all doc relevant data that meta computes using a compiler as actual data into the model, e.g. super classes.

It sounds like metadoc is doing that (without having checked that). If that is the case, we can basically take a subset of metadoc's model as we go and eventually hopefully the full model and concentrate on the backends and improving metadocs model rather than newly inventing it from scratch.

So we should adapt the current model to metadoc's model (if it is true that it is designed as described above).

plug scala meta in the front that starts with source code and write a converter that converts the corresponding trees to our trees. Plus wrap it all up as a full circle prototype.

What is this and why does the world need this?

How to run it and play with it?

What can you work on to improve this / important missing features?

automate turning the generated latex file into a PDF, ideally from SBT, or alternatively from a .bat file

Figure out if meta already works for resolving

• parent types
• inferred return types (decltype = None)
• link companion / classes

If it does, let's use it to do that, otherwise let's just document here, where meta isn't ready yet. Integrating meta is fun, but we should aim for not being slowed down or blocked by meta's experimental stage. So not spend too much time on working around meta problems.

Clean up rough edges to make the "user experience" nice. Someone should be able to just install pdflatex, clone the project and smoothly run it on the sample sources.

Do we want to generate our HTML from Latex or make it its own independent output format? We must choose!

some strings are weirdly indented, they should be something like (or close to)

class Baz{
  def foo = s"""dsfsfdsf"""
  def bar = s"""
    fsfsdf
    sdfsdfsdf
    sdfsdf
  """
}