Question

This might be a doclet-implementation-specific question, but I believe its really a JavaDoc configuration issue I’m dealing with here.

I’m trying to get the yDoc UML Doclet to work so that it will generate UML diagrams for my Java app as part of the Ant build. I downloaded the project (community edition) and have tried adapting their build-sample.xml but can’t quite get it to work.

Here’s my project directory structure:

MyProject/
    src/main/java/
        <All the Java sources I want documented and diagrammed>
    bin/main
        <Compiled binaries of src/main/java/>
    lib/
        styleed.jar
        ydoc.jar
    resources/
        <All the yDoc resources that came with the download>
    umldoclet/
        <Where I want all JavaDocs to go>
    build.xml

Here’s build.xml:

<project name="MyProject" default="ydoc" basedir="." xmlns:ivy="antlib:org.apache.ivy.ant" xmlns:jacoco="antlib:org.jacoco.ant">

    <!-- The "compile" task and all its dependencies omitted for brevity,
         but they all absolutely work 100% and "compile" places compiled
         CLASS files under bin/main. -->

    <target name="ydoc" depends="compile">
        <property name="ydoc.home" value="${basedir}"/>

        <javadoc source="1.5" destdir="./umldoclet" additionalparam="-breakiterator">
            <packageset dir="src/main">
                <include name="java/**"/>
            </packageset>
            <doclet name="ydoc.doclets.YStandard" path="${ydoc.home}/lib/ydoc.jar;${ydoc.home}/resources">
                <param name="-author"/>
                <param name="-generic"/>
                <param name="-umlautogen"/>
                <param name="-filterpath" value="./lib/ydoc.jar"/>
                <param name="-filter" value="ydoc.filters.ExcludeFilter"/>
                <param name="-tag" value="y.precondition"/>
                <param name="-tag" value="y.postcondition"/>
                <param name="-tag" value="y.complexity"/>
                <param name="-tag" value="param"/>
                <param name="-tag" value="return"/>
                <param name="-tag" value="see"/>
                <param name="-tag" value="y.uml"/>
            </doclet>
        </javadoc>
    </target>
</project>

When I run the ydoc task, even running Ant in “verbose” mode with the -v argument, I see the [ydoc] task getting called in the Ant Console, followed by a log statement that reads “Generating Javadoc” and about 20 lines from the verbose output regurgitating the yDoc params back to me, then a final log message saying “Javadoc execution”. Then, the following stunningly-vague IOException:

BUILD FAILED
<my-eclipse-home>/MyProject/build.xml:200: Javadoc failed: java.io.IOException: Cannot run program "javadoc": java.io.IOException: error=2, No such file or directory
    at org.apache.tools.ant.taskdefs.Javadoc.execute(Javadoc.java:1765)
    at org.apache.tools.ant.UnknownElement.execute(UnknownElement.java:291)
    at sun.reflect.GeneratedMethodAccessor4.invoke(Unknown Source)
    at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
    at java.lang.reflect.Method.invoke(Method.java:616)
    at org.apache.tools.ant.dispatch.DispatchUtils.execute(DispatchUtils.java:106)
    at org.apache.tools.ant.Task.perform(Task.java:348)
    at org.apache.tools.ant.Target.execute(Target.java:392)
    at org.apache.tools.ant.Target.performTasks(Target.java:413)
    at org.apache.tools.ant.Project.executeSortedTargets(Project.java:1399)
    at org.apache.tools.ant.Project.executeTarget(Project.java:1368)
    at org.apache.tools.ant.helper.DefaultExecutor.executeTargets(DefaultExecutor.java:41)
    at org.eclipse.ant.internal.launching.remote.EclipseDefaultExecutor.executeTargets(EclipseDefaultExecutor.java:32)
    at org.apache.tools.ant.Project.executeTargets(Project.java:1251)
    at org.eclipse.ant.internal.launching.remote.InternalAntRunner.run(InternalAntRunner.java:424)
    at org.eclipse.ant.internal.launching.remote.InternalAntRunner.main(InternalAntRunner.java:138)
Caused by: java.io.IOException: Cannot run program "javadoc": java.io.IOException: error=2, No such file or directory
    at java.lang.ProcessBuilder.start(ProcessBuilder.java:475)
    at java.lang.Runtime.exec(Runtime.java:610)
    at org.apache.tools.ant.taskdefs.Execute$Java13CommandLauncher.exec(Execute.java:862)
    at org.apache.tools.ant.taskdefs.Execute.launch(Execute.java:481)
    at org.apache.tools.ant.taskdefs.Execute.execute(Execute.java:495)
    at org.apache.tools.ant.taskdefs.Javadoc.execute(Javadoc.java:1759)
    ... 15 more
Caused by: java.io.IOException: java.io.IOException: error=2, No such file or directory
    at java.lang.UNIXProcess.<init>(UNIXProcess.java:164)
    at java.lang.ProcessImpl.start(ProcessImpl.java:81)
    at java.lang.ProcessBuilder.start(ProcessBuilder.java:468)
    ... 20 more

Is there any way to get more details out of Ant? To find out what file or directory its referring to in the exception? Any JavaDoc/yDoc gurus ever ran into this before? Is my project directory structure set up incorrectly, or different than what the Ant build is looking for? I believe I have my doclet/path attribute set up correctly, and using the correct path separators (I’m on Ubuntu Linux). For the life of me I can’t figure out where to go from here, or how to go about diagnosing the underlying issue here! Thanks in advance!

Edit/Update:

Thanks to everyone so far for the suggestions. I am doing away with Eclipse totally (as far as the build is concerned and just running Ant from the command-line; this is fine for now. When I do this, I get a successful build (so Eclipse was at least partly the culprit), however still no yDoc generation.

Now, when I run Ant from the terminal with the verbos (-v) option, here’s what I see:

Hundreds of warnings that look the same, but with different classes:

[javadoc] Constructing Javadoc information...
[javadoc] /<path-to-my-project>/MyProject/src/main/java/com/some/pkg/SomeObject.java:11: package org.springframework.beans.factory.annotation does not exist
[javadoc] import org.springframework.beans.factory.annotation.Autowired;
[javadoc]                                                    ^

After hundreds of those, I get the following output (1 of these for every package in my source tree):

[javadoc] javadoc: warning - No source files for package java.com.some.pkg.<whatever>

Last, the final section of the verbose build output:

[javadoc] Valid license file found.
[javadoc] Registered Filter ydoc.filters.ExcludeFilter ...
[javadoc] Registered Taglet for tag @y.complexity ...
[javadoc] Registered Taglet for tag @y.precondition ...
[javadoc] Registered Taglet for tag @y.postcondition ...
[javadoc] Registered Taglet for tag @y.author ...
[javadoc] 1 error
[javadoc] 109 warnings
[javadoc] javadoc: error - No public or protected classes found to document.

BUILD SUCCESSFUL
Total time: 6 seconds

Furthermore, if it were executing correctly, it should be places all the JavaDocs under the uml-doclet/ directory in my project root. It does no such thing!

So it looks like there are several more things going on:

1. The JavaDoc can’t see my 3rd party dependencies (such as Spring, Camel, etc.); hence the list of hundreds of warnings
2. It can’t find any of my sources to document

Again, the bounty goes to anyone who can help me get this working. Thanks again for all the help so far!

Answer 1

If you execute ant with -verbose -debug you will either see these lines:

Setting project property: ydoc.home -> /var/tmp/ydoc-test
  [javadoc] scanning /var/tmp/ydoc-test/src/main for packages.
dirset: Setup scanner in dir /var/tmp/ydoc-test/src/main with patternSet{ includes: [java/**] excludes: [] }
  [javadoc] Generating Javadoc
  [javadoc] Executing '/usr/lib/jvm/java-7-openjdk-amd64/bin/javadoc' with arguments:
  [...]

Or you will see these lines:

Setting project property: ydoc.home -> /var/tmp/ydoc-test
  [javadoc] scanning /var/tmp/ydoc-test/src/main for packages.
dirset: Setup scanner in dir /var/tmp/ydoc-test/src/main with patternSet{ includes: [java/**] excludes: [] }
  [javadoc] Generating Javadoc
  [javadoc] Executing 'javadoc' with arguments:

In the first case Eclipse/Ant have found a valid javadoc command and tell you so in the line [javadoc] Executing >FULL_PATHNAME_TO_JAVADOC>. In the second case it only talks about javadoc without any pathname and the debug output will show your exceptions later.

I assume that your case is the second one, but please check it!

If Eclipse / Ant don’t know the location of javadoc you first should simplify things by taking Eclipse out of the equation: Use the command line and check that typing these commands do not result in in a “command not found” message:

java
javac
javadoc

I assume that the first one is OK (after all you can run Eclipse as shown in you stacktraces). If the second and third command are not found, you have not installed an JDK but only a JRE on your computer. Install one and restart Eclipse.

If on the other hand javac is found but javadoc not, then your JDK is broken.

If both javac and javadoc are found then Eclipse simply does not know about it. But before going back to Eclipse type a last command in the command shell:

readlink -m $(which javadoc)/../..

Remember the path readlink gives you.

In Eclipse goto “Window -> Preferences -> Java -> Installed JREs”. In the list select the entry with the checked checkbox and press “edit”. If the line “JRE home” is not the same as the path readlink gave you, then most likely your Eclipse is configured to use only a local JRE but not your installed JDK.

If that’s the case then cancel that “Edit” dialog, press “Add”, select “Standard VM” and enter the path readlink gave you. After entering that path correctly Eclipse should fill out the other fields for you, hence you can just say “OK”. Back in the “Installed JRE” list tick on the new item.

After that the javadoc task per se should start.

EDIT

However you need some more adjustments:

First: In this part:

       <packageset dir="src/main">
            <include name="java/**"/>
        </packageset>

you are mixing the source directoy and the package parts. It should read:

       <packageset dir="src/main/java">
       </packageset>

Also javadoc likes to have access to referenced classes. Therefore you should add the same classpath to javadoc as you used for compiling your code. So add an appropriate <classpath> section right after </packageset>. This will take care of the “package xyz does not exist” warnings.