27

I would like to be able to generate javadoc for my maven projects even when running under a JRE instead of a JDK, where the javadoc command invoked by maven is found. In other words, not relying on anything but what is in the JRE and what Maven can download and use as artifacts.

Is there any easy way to generate javadocs at all with Maven without needing to use code only found in the JDK?

EDIT: Apparently it is important to understand why I want to do this. We are a small team in a larger organization with yearly releases of our product suite, which our customers then upgrade when it is convenient for them (due to the sheer scale of the deployments this is expensive and time demanding, so it is common to skip one or several releases) and we make a living of being able to provide bugfixes and new functionality on short notice for existing deployments on whatever version the customer in question is running. As an example I recently did a bugfix for a component I wrote five years ago which had been largely untouched since.

Hence long term stability of our build process is very important to us as well as being able to use new versions of Java as they become available. We have migrated our complete build environment to Maven - which buys us permanently frozen artifacts in Maven Central - and have now started to look at what else we need to do.

With the recent announcement that future versions of javac will not support old targets (http://openjdk.java.net/jeps/182) we have concluded that our long term goal is to minimize our dependencies on the underlying Java environment, preferably to just the plain JRE. We are in the process of completely replacing javac from the JDK with the Eclipse compiler which is available from Maven Central, and now we look at javadoc generation.

Thorbjørn Ravn Andersen
  • 73,784
  • 33
  • 194
  • 347
  • I believe that javadocs only comes with jdk, as it is part of the options for the java compiler command, but Im not 100% sure. – David says Reinstate Monica Jun 11 '13 at 15:33
  • think it is specific for maven, but always it is possible to reinvent the wheel: write a library which parse .java files and generate the html files, I don't see a reason why to do it, but is a solution and can run in described conditions –  Jun 11 '13 at 15:34
  • You may extract the tools.jar from a JDK and write a maven plugin to call the Javadoc Main class , see [Javadoc Main](http://www.docjar.com/docs/api/com/sun/tools/javadoc/Main.html) – gma Jun 11 '13 at 15:48
  • @Dgrin91 Javadoc is a separate tool, not part of the compiler. – gparyani Jun 11 '13 at 16:13
  • @matheszabi that might be stretching the "easy way" part a bit – Thorbjørn Ravn Andersen Jun 12 '13 at 08:54
  • 1
    Out of curiosity, why? It sounds more like you want to create a distro, not "run a Maven project", which is a development task. – Dave Newton Jul 14 '13 at 18:46
  • @DaveNewton to be able to do a complete build of our software with the only requirement being a JRE is installed. I don't know where you got the idea of a distribution, but I can assure you that is not the goal here. – Thorbjørn Ravn Andersen Jul 14 '13 at 20:29
  • That won't be possible, obviously you need the JDK to compile. Why would you make people do a build when you can give them a distribution? – Dave Newton Jul 14 '13 at 20:37
  • @DaveNewton I know for a fact it is possible to compile with maven using the Eclipse compiler. I do not want _people_ to do a build. I want _our_ build process to require only a JRE plus whatever Maven wants to download. Can you assist in getting the javadoc part done too? – Thorbjørn Ravn Andersen Jul 14 '13 at 21:09
  • You cannot possibly 'do a complete build' with only a JRE. The question embodies a contradiction in terms. – user207421 Jul 14 '13 at 21:56
  • @EJP Please have a look at http://www.gabiaxel.com/2011/10/replacing-javac-with-eclipse-compiler.html. The additional part to realize is that the eclipse compiler is downloaded by maven itself. – Thorbjørn Ravn Andersen Jul 14 '13 at 22:11
  • 3
    So? What's the problem with using a JDK? How are you going to run the JAR command? jarsigner? rmic? idlj? ...? You can fight the standard JDK/JRE packaging all you want, and maybe get something working, but what's the point? You're just making a rod for your own back here. – user207421 Jul 14 '13 at 22:20
  • @EJP thank you for sharing your opinion. If you also have input on what I am actually asking, I would like to hear that too. – Thorbjørn Ravn Andersen Jul 14 '13 at 22:22
  • So maybe your question should have included the rest of the information you are only now sharing-without any context you are likely to get people trying to understand. – Dave Newton Jul 14 '13 at 22:43
  • @DaveNewton I cannot see why this additional information is important. The question is simple - how can I create javadoc with maven using only a JRE? How can I phrase it better? – Thorbjørn Ravn Andersen Jul 15 '13 at 07:05
  • @ThorbjørnRavnAndersen I know you can't, despite seeing a fair amount of discussion trying to understand *why* this is a requirement or what the actual *point* of doing this is. Since you're already expecting your users to deal with Maven and its associated issues, it's not unreasonable to assume that (a) they already *have* a JDK, and/or (b) they wouldn't be better served by a distro. You don't get to decide how people respond to your questions, and without providing reasonable context, you're bound to get people questioning why you're doing what you're doing. Good luck. – Dave Newton Jul 15 '13 at 12:12
  • @DaveNewton I do not know why you talk about "users". As mentioned earlier this is for our own team only and we only have "developers" doing this, not "users". The reason is very simple - by nailing down all requirements as maven artifacts (which is the side effect of using the Eclipse compiler instead of javac in the JDK) we have as much control over our build environment as possible for a very long time. Oracle has recently announced that javac will support only three versions back, meaning that upgrading may break our current build process (yes, we support 1.4 deployments). – Thorbjørn Ravn Andersen Jul 15 '13 at 13:19
  • @DaveNewton so when it is our own team needing to do this as part of the daily work process, then it does not make sense to talk about distributions etc etc, as it is - hopefully - just a matter of maven downloading the appropriate artifacts and then creating the javadoc artifact. The bits we ship out to customers should hopefully be the same (so no "users" or "distributions" there either). This is important to us because we have very long support cycles - the other day I did a bugfix in a program untouched for five years - and I am aware that this is not a common situation. – Thorbjørn Ravn Andersen Jul 15 '13 at 13:34
  • 2
    @ThorbjørnRavnAndersen I think it's odd your Java development team doesn't have a JDK available, even if it's only to test the output of the Eclipse compiler to catch edge case compilation issues--sounds quite risky to me. – Dave Newton Jul 15 '13 at 14:05
  • @DaveNewton Sure we do. The idea is not to avoid installing a JDK, but to avoid _needing_ a JDK. – Thorbjørn Ravn Andersen Jul 15 '13 at 14:09

7 Answers7

11

Get the source of the JavaDoc from the OpenJDK, and build your own JAR from it with all the relevant JavaDoc classes. Write a maven plugin that relies on your JAR, and call com.sun.tools.javadoc.Main.main from it.

It does not look like you need to open up your sources when using OpenJDK's classes, you should be OK to distribute the resultant plug-in without harsh restrictions.

Even if the terms do not cover the tools, you could write an Open Source GPL-2 plugin for maven, and make it a separate product that you distribute under GPL-2. Your product would then download and install the plugin using maven plugin:download, thus separating out your JavaDoc plugin from the rest of your code.

Of course you should run this suggestion by your legal department before following this advice.

Community
  • 1
  • 1
Sergey Kalinichenko
  • 714,442
  • 84
  • 1,110
  • 1,523
  • Are you absolutely certain that the license for javadoc allows me to do this without having to carry artifacts around in my build - the link only refers to using openJDK as a JVM, not explicitly using its source code? My research of the Oracle openjdk license basically boiled down to that javadoc is GPL and even linking with it is enough - according to the license - to make the whole application GPL. Unfortunately that license is not acceptable in this situation. Also I would like a Solution acceptable to maven central. – Thorbjørn Ravn Andersen Jul 14 '13 at 22:16
  • @ThorbjørnRavnAndersen Even if the terms did not cover tools, you could write an Open Source GPL-2 plugin for `maven`, and make it a separate product that you distribute under GPL-2. Your product would then download and install the plugin using `maven plugin:download`, thus separating out your JavaDoc plugin from the rest of your code. – Sergey Kalinichenko Jul 14 '13 at 22:35
  • OpenJDK license mentioned: http://openjdk.java.net/legal/assembly-exception.html – Thorbjørn Ravn Andersen Jul 15 '13 at 10:30
  • "build your own JAR from it"... any advantage over just using tools.jar from jdk? – Glen Best Jul 22 '13 at 03:39
  • 1
    @GlenBest please re-read the question - the idea is to minimize external dependencies outside our control. – Thorbjørn Ravn Andersen Mar 24 '14 at 11:19
  • I understand the Q. Perhaps you missed my point? Getting source code from Open JDK and building your own JAR from it has no less dependencies than simply using tools.jar & executing it in combination with the JRE... – Glen Best Mar 26 '14 at 01:59
  • Accepted as the way to solve this, would be to decouple the hard binding of the javadoc maven plugin to the JDK `javadoc` command, and provide an alternative implementation. – Thorbjørn Ravn Andersen Jul 16 '14 at 10:41
7

  1. An aside (not answering your Q directly):

    The Eclipse Development Guide recommends using both the Eclipse compiler and the JDK tool (for the javadoc menu option).

    http://help.eclipse.org/juno/index.jsp?topic=%2Forg.eclipse.jdt.doc.user%2Freference%2Fref-export-javadoc.htm

    Eclipse Generate Javadoc Wizard: what is "Javadoc Command"?

    From your comments, it's clear you don't want to go this way, which is your right :)

  2. Answer to your Q. There a few open source / free javadoc tools that you can invoke from your build tool:

    Pros: Work outside of JDK. Some have richer documentation than javadoc.
    Cons: Might have some non-standard behaviour compared to javadoc (might not be an issue for you).

albert
  • 8,285
  • 3
  • 19
  • 32
Glen Best
  • 22,769
  • 3
  • 58
  • 74
2

You can use a product called doxygen. It is typically used to create documentation for C++ or other languages that don't have a javadoc product built-in.

You can set up doxygen to read the javadoc annotations and product similar output to javadoc.

albert
  • 8,285
  • 3
  • 19
  • 32
Andrew T Finnell
  • 13,417
  • 3
  • 33
  • 49
1

The command that generates the java docs is actually called javadoc and it is only available with the JDK.

Ayman
  • 1,682
  • 15
  • 17
1

From the Javadoc FAQ :

String[] javadocargs = { "-d", "docs",
                         "-sourcepath", "/home/user/src",
                         "java.applet" };
com.sun.tools.javadoc.Main.main(javadocargs);

tools.jar needs to be in your classpath.

RealHowTo
  • 34,977
  • 11
  • 70
  • 85
  • Is tools.jar shipped with JRE? – Menelaos Jul 14 '13 at 20:21
  • `tools.jar` is not available with a JRE which is what I want to do. – Thorbjørn Ravn Andersen Jul 14 '13 at 20:25
  • 1
    Well ... copy it for a JDK distribution and make it available to your JRE installation ! – RealHowTo Jul 14 '13 at 20:36
  • @RealHowTo I would like to do it without a binary found only in the JDK. Copying a binary only found in the JDK was not the answer I was looking for, and I am not sure the Oracle license permits doing this in a team setting. – Thorbjørn Ravn Andersen Jul 14 '13 at 21:13
  • 1
    I understand that you're not allowed to redistributed incomplete JDK but in a development environment for your own usage, I guess it'S ok ... but I'm not a lawyer ;-) – RealHowTo Jul 14 '13 at 21:49
  • http://stackoverflow.com/questions/6755414/can-we-redistribute-oracle-tools-jar says you can redistribute a jre with some special extra files, including tools.jar. We did this in the past to redistribute tomcat with a jre, and tools.jar to compile jsp's. – GeertPt Jul 20 '13 at 07:26
1

We offer a tool called DocFlex/Javadoc, which is already mentioned here by Glen Best (although a little bit incorrectly).

But before going deep into this, I would like to provide some intro to what this is all about.

Basically, Javadoc (that is provided by JDK) is a caller of two things:

  1. The Java parser
  2. A doclet

Javadoc starts by calling the Java parser to collect information about Java sources, from which it builds a DOM-like structure represented in the form of Doclet API. Then, it calls a doclet. This is a Javadoc plug-in that uses Doclet API as a data-source to generate by it any kind of output.

What you see as the standard JavaDoc is generate by the Standard Doclet. So, you can imagine that doclet is the largest part of the whole Javadoc implementation.

Now, about our DocFlex/Javadoc software. Essentially, it is a tool for fast development of special doclets, which utilizes our much more general technology for template-driven documentation generators. (Actually, our focus is rather away from Javadoc stuff. So, it is more a by-product of the main thing).

In our interpretation, the doclets themselves (as documentation generators) are programmed in the form of special template sets. Those templates are more akin to XSLT scripts, but conceptualy only (we do not use XSLT somewhere in background). The DOM-like organization of the Doclet API allowed us to utilize an XSLT/XPath-like approach general to our technology. So, each doclet consists of two things:

  1. The template interpretor
  2. A template set

Here, the template set is an interchangable part (which is actually the focus of our tool).

Currently, we provide a ready-to-use JavadocPro template set, which generates HTML output equivalent to the standard JavaDocs (with some important extra-features not available in the Standard Doclet). Here, you can see a demo JavaDoc generated with it:

enter image description here

The whole DocFlex/Javadoc is a commercial product. But we also provide a light edition of it called DocFlex/Doclet, which is free. It includes only template interpreter and some ready template sets (including JavadocPro). So, you can use it to generate JavaDoc very similar to the standard one (in HTML) as well as RTF documentation.

Now, concerning the main question. Can our tool be used without JDK?

No. Because, as being a Javadoc plug-in (the doclet part of our tool), it still needs Javadoc.

On the other hand, what is missing to make it fully JDK independent is a Java parser, and we don't need a full-blown Java parser at that, because we are not generating an executable code. What we need is something lightweight, able to build a structure like Doclet API.

If we knew what a demand for such a thing might be, we could consider developing one. Any further questions? Let us know by email (found on our website)!

Community
  • 1
  • 1
Leonid Rudy
  • 255
  • 4
  • 5
  • @GlenBest It is that you wrote: `2. Answer to your Q. .... Pros: Work outside of JDK.` It's about our tool, yes? That's incorrect. Our JavaDoc generator cannot work outside JDK. (We can do that by investing some efforts. But that's a different story.) Otherwise, I'm very much pleased that you mentioned our tool! – Leonid Rudy Jul 16 '13 at 11:13
1

why don't you download javadoc source at http://docs.oracle.com/javase/6/docs/technotes/guides/javadoc/standard-doclet.html#source

and rebuild it to suit you needs in maven

blganesh101
  • 3,647
  • 1
  • 24
  • 44