javadoc problem

[Steve Appling]

I think I understand the javadoc issues a little more, but still don't know
exactly what to do about it.

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.

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.

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.

I guess I'm just all around confused this afternoon.  Perhaps I just ate too
much lunch.  I'll go get some coffee.
--
Steve Appling
Automated Logic Research Team

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email

[Adam Murdoch-2]

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.

> I guess I'm just all around confused this afternoon.  Perhaps I just
> ate too much lunch.  I'll go get some coffee.

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email

[hdockter]

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?

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.

- Hans

--
Hans Dockter
Gradle Project Manager
http://www.gradle.org

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email

[Adam Murdoch-2]

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