search

cvogt / cbt

CBT - fun, fast, intuitive, compositional, statically checked builds written in Scala
Other
488 stars 60 forks source link

print build file method scaladoc strings as docs in `cbt help` #252

Open cvogt opened 7 years ago

cvogt commented 7 years ago

A mechanism that makes scaladoc strings accessible to cbt, so it can use it when printing help would be great. Maybe via scala meta or maybe a patch to scalac that adds them as annotations to the byte code (I remember there being a scala issue for it, but I can't find it).

cc @olafurpg

olafurpg commented 7 years ago

Do you mean something like

$ cat build.scala
object Build {
  /** docs for compile */
  def compile = ???
}
$ cbt help compile
docs for compile

If we know the source file and class/object where that method exists, we could do this with meta. However, scala.meta has only syntactic information so it won't be able to correctly resolve traits/overloading/...

Possibly related, this PR extracts docstrings via a macro that uses the actual scaladoc parser in scalac.

cvogt commented 7 years ago

@olafurpg yes, that's what I mean. The PR looks very related indeed. Had a feeling you may know something about this ;).

At runtime source file mapping can be taken from zinc, also see https://github.com/cvogt/cbt/issues/206

olafurpg commented 7 years ago

The scalac DocParser is quite complicated to work with because it supports advanced features such as typechecking references in the docstrings. I don't we need any of that for this issue.

At runtime source file mapping can be taken from zinc, also see #206

Cool! With a filename + enclosing object/trait/class name + method name it should be quite straightforward to pull out the docstring using scala.meta. I'm happy to help implement this if you're interested, I know zero about zinc though :)

rockjam commented 7 years ago

I guess related to #182

cvogt commented 7 years ago

@olafurpg sounds good, I'll pull you in at some point :)

cvogt commented 7 years ago

would also be awesome to show these doc strings in fish shell completions

olafurpg commented 7 years ago

Do you know the source file where the docstring exists? We recently added some docstring utilities in scalameta contrib.

cvogt commented 7 years ago

We should be able to locate those, yes. CBT has all sources available. We care about doc strings of methods of a number of classes which happen to have these properties

  1. top-level
  2. non-ambiguous names
  3. transitively extending BaseBuild

1 and 2 should make it easy to find them syntactically with meta. 3 should be doable even with Java Reflection.

If somebody wants to take a stab at this, I am happy to help from the CBT side with whatever, e.g. provide a list of candidate file names that would have to be analyzed with meta.

olafurpg commented 7 years ago

Here's an example of how to use AssociatedComments from scala.meta contrib https://github.com/scalameta/scalameta/blob/6605119ceb3ba10c0ae4feb6b2388ead3486051a/scalameta/contrib/src/test/scala/scala/meta/contrib/AssociatedCommentsTest.scala

The dependency for this module http://search.maven.org/#artifactdetails%7Corg.scalameta%7Ccontrib_2.12%7C1.6.0%7Cjar