"sbt doc" and mixed Scala/Java projects

[Kaspar Fischer]

Hi everybody,

I am using SBT 0.12.2's sbt doc task to generate the documentation in ScalaDoc format of the source of a mixed Java/Scala project.

My Scala code uses the ScalaDoc documentation syntax, however, my Java code uses ordinary JavaDoc syntax.

When I run sbt doc, the generated documentation contains my Java classes, albeit without any documentation.

Is there a way to get the Java documentation (it does not necessarily have to be in the same HTML file(s) as the Scala documentation)?

Thanks for any pointers!

Kaspar

[eugene yokota]

Hi Kasper,

I'm not sure if this would help, but Akka team has written a compiler plugin that generates Java source from Scala source,

so one can generate JavaDoc. I've wrapped the feature in [sbt-unidoc][1].

Not all Scala source generates clean Java source, so it may or may not work.

-eugene

  [1]: https://github.com/sbt/sbt-unidoc#how-to-unify-javadoc

[Kaspar Fischer]

Hi Eugene,

Thanks for your message and the link. Much appreciated. Will take a look and see whether it helps in my particular project.

Cheers,

Kaspar

[Mark Harrah]

For background, javadoc only understands Java sources. scaladoc does not understand javadoc comments, so although it will process Java sources, it doesn't understand the javadoc syntax. scaladoc does not link to javadoc, so running both would result in independent documentation sites.

-Mark

On Mon, 8 Jul 2013 06:37:05 -0700 (PDT)
Kaspar Fischer <kaspar....@dreizak.com> wrote:

> Hi Eugene,
>
> Thanks for your message and the link. Much appreciated. Will take a look
> and see whether it helps in my particular project.
>
> Cheers,
> Kaspar
>
> On Monday, 8 July 2013 15:35:27 UTC+2, eugene yokota wrote:
> >
> > Hi Kasper,
> >
> > I'm not sure if this would help, but Akka team has written a compiler
> > plugin that generates Java source from Scala source,
> > so one can generate JavaDoc. I've wrapped the feature in [sbt-unidoc][1].
> > Not all Scala source generates clean Java source, so it may or may not
> > work.
> >
> > -eugene
> >
> > [1]: https://github.com/sbt/sbt-unidoc#how-to-unify-javadoc
> >
> >
> > On Monday, July 8, 2013 9:06:05 AM UTC-4, Kaspar Fischer wrote:
> >>
> >> Hi everybody,
> >>
> >> I am using SBT 0.12.2's sbt doc task to generate the documentation in
> >> ScalaDoc format of the source of a mixed Java/Scala project.
> >>

> >> My Scala code uses the ScalaDoc documentation syntax<https://wiki.scala-lang.org/display/SW/Syntax>,

> >> however, my Java code uses ordinary JavaDoc syntax.
> >>
> >> When I run sbt doc, the generated documentation contains my Java
> >> classes, albeit without any documentation.
> >>
> >> Is there a way to get the Java documentation (it does not necessarily
> >> have to be in the same HTML file(s) as the Scala documentation)?
> >>
> >> Thanks for any pointers!
> >> Kaspar
> >>
> >
>

> --
> You received this message because you are subscribed to the Google Groups "simple-build-tool" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to simple-build-t...@googlegroups.com.
> To post to this group, send email to simple-b...@googlegroups.com.
> Visit this group at http://groups.google.com/group/simple-build-tool.
> For more options, visit https://groups.google.com/groups/opt_out.
>
>

[Kaspar Fischer]

Thank you, Mark, for the clarification.

I understand that each tool understands only its own documentation syntax. However, I am wondering whether there is a possibility to have sbt doc run also JavaDoc, for example, producing an independent documentation site for the Java classes (independent in the sense that the HTML files may be different from the ones that ScalaDoc produces)?

Kaspar

[Mark Harrah]

The original work to add javadoc support was discussed here:

https://groups.google.com/d/topic/simple-build-tool/t1H1qhvtUAA/discussion

Running both was ultimately decided against by default and I think it wasn't made an option for compatibility reasons at the time. (I think it was in another thread or maybe in the pull request discussion.)

In practice, if you have a mixed Java and Scala project and the sources do not have cycles between the different languages*, you can split them into separate subprojects and run the different doc generators that way.

If there are mixed sources with cycles, I'm not sure if that would work. You would probably have to compile the classfiles with `compile` first and then put those on the classpath in order to process just the .java or just the .scala files. This would probably work for javadoc, since that is how javac is handled, but I'm not sure about scaladoc.

-Mark

* A.java->B.scala->C.java or
D.scala->E.java->F.scala

On Mon, 8 Jul 2013 09:11:07 -0700 (PDT)

[Seth Tisue]

see also https://issues.scala-lang.org/browse/SI-4826

[Indrajit Raychaudhuri]

Now if I could pray an angel to really get ready to fly down from heaven :)

- Indrajit

On Jul 10, 2013, at 11:27 AM, Seth Tisue <se...@tisue.net> wrote:

see also https://issues.scala-lang.org/browse/SI-4826