Hans Dockter wrote:
On Sep 24, 2009, at 10:42 PM, Adam Murdoch wrote:
Steve Appling wrote:
I think I understand the javadoc issues a little more, but still
don't know exactly what to do about it.
It's actually fixed in trunk. I'm in the process of upgrading to a
new snapshot, but I wanted to investigate the heap usage before doing
so.
The java plugin doesn't seem to set up the classpath correctly for
the javadoc task.
Currently core:javadoc fails, but if I add
javadoc {
configuration = files(source.main.compileClasspath,
source.main.classes)
}
to core.gradle, it works.
This is the default in trunk now.
I copied this pattern from the root build.gradle, but I don't
understand where the configuration property of the JavaDoc task
comes from. It seems like this should be the classpath property,
but if I don't set configuration it gives an error. I don't see a
setConfiguration in JavaDoc or any of its ancestors.
I renamed it yesterday. It was configuration, now its classpath.
Should the output directory (source.main.classses) just be added to
the classpath convention in JavaPlugin.configureJavaDoc? I'm a
little confused about the connection between the classpath
convention and the configuration property.
I'm also confused about why running 'gradlew javadoc' runs javadoc
on both the root project and all the subprojects, but running
'gradlew explodedDist' which depends on the root javadoc, does not
run javadoc on the subprojects.
explodedDist doesn't depend on the subproject's javadoc tasks because
it does not include their output in the distribution. It depends only
on :javadoc, which generates a single javadoc batch which documents
all the subprojects.
So, when you run 'gradle explodedDist', you will only end up
executing :javadoc
When you run 'gradle javadoc', you're asking Gradle to execute any
task named 'javadoc' it finds in the current project and all
subprojects. Which is why it ends up executing all the javadoc tasks.
We don't care about the output of the individual subproject's javadoc
tasks, and it would be much better if they did not exist. Ditto the
groovydoc tasks.
Right, we don't care (yet) about the output of the individual
subproject's. But is it really a problem to have this functionality?
Possibly not. It's noisy in a couple of respects:
- there's extra tasks in the build which we don't use
- the subproject's javadoc/groovydoc tasks generate the documentation
for everything (ie the default), whereas the root javadoc/groovydoc
tasks generate the documentation for the API only.
To me, this is a smell that we've not got the model quite right.
If so, what can we do?
- We could disable the javadoc tasks.
- We could provide functionality for removing tasks.
- Reconsider the name matching strategy for multi-project build
execution.
I would say a better option is to improve the model so that we know
whether or not API documentation is required for a project. For example,
if we knew that the core project is a library bundled into a
distribution by the root project, then we would know that it does not
need its own javadoc task, and that we should build the aggregate
javadoc in the root project instead.
Or if we knew that the core project is a library which is distributed
stand-alone, then it would need its own API documentation, and we would
add a javadoc/groovydoc/scaladoc task as appropriate.
I think this comes down to some missing concepts:
- A project which aggregates several other projects into some
distribution. In this case, a distribution might be a fat jar or a war
or an application image or whatever.
- A project or source set which is bundled as a java library. That is we
know the difference between source which is used internally somewhere in
the same build, and source which is to be published as a JAR for use
outside the build.
- A source set has an API.
Adam
---------------------------------------------------------------------
To unsubscribe from this list, please visit:
http://xircles.codehaus.org/manage_email
