Single documentation for mixed (Scala/Java) project?

Question

For a project with modules in Scala and Java (side by side), how to combine scaladoc with javadoc to provide a single view of the documentation for the project?

(this could be using maven, or ant, or sbt, more a general question).

Any thoughts and experiences appreciated.

Claudeclaudel

+1 Even if the ScalaDoc and JavaDoc remain separate, it would be great to be able to cross-link references. – Pluckless

Answer 1

With Scala 2.8's new scaladoc that will replace the one used with Scala 2.7, the differences will be even more striking. However, there was a request that a function be provided that translated scaladoc into javadoc format, for use by IDEs when displaying help.

If this function becomes available, then something that generates javadocs from scaladocs would be theoretically feasible.

But for any of that to become true, the people who have interest in such a thing would have to speak up at the appropriate fora. And, of course, if they are too small a group, it is likely nothing happens unless they do it for themselves.

Archetype

My thoughts are more along the lines of people creating libraries in scala, that would have been once created in java. So both java lang users may want to use them - the fact that the library is written in scala doesn't have to concern the consumer too much. For this purpose, scaladoc is adequate, but I guess if you really want to hide the fact that it is scala, it doesn't cut it - I will look into it futher, thanks for your answer ! – Claudeclaudel

Answer 2

What's de advantage of having Scaladoc <> Javadoc? There is a huge number of tools for Javadoc and almost anything for Scaladoc. The mainstream IDEs (Eclipse, Netbeans, Idea - real world enterprise development - not academic research) knows nothing about Scaladoc. Seems like being in Siberia: isolated.

Mimimimic

I guess that was my point. If you are writing a library for general consumption, and you want the consumers to not care it was written in scala, than javadoc would be nice (of course you have to take care in how you write the scala for the public interface anyway). – Claudeclaudel

Answer 3

Scaladocs and javadoc are very different, with different formats. They are just two different animals and I don't think it makes sense to combine them. So, AFAIK, Maven doesn't offer any support for that (which is not surprising), just generate both of them separately.

Blunder