Jar Task DSL Documentation

The top quick-link bar is very useful. The content along the right column about news, etc. clearly is a work in progress, as it mangles the DSL guide and to a lesser extent the User Guide.

The real point is that someone was asking me why project(’:something’).jar.output was not working correctly. Going to the DSL documentation, there is no mention of an outputs property or method – note they were attempting to use “output” but really wanted to use “outputs” but couldn’t find the documentation.

Worse, following the API documentation for Jar goes to the groovydoc, which is known to be problematic, and doesn’t show any inherited methods.

Granted, Jar is listed as a Task type, so jumping over to the core type of Task reveals “outputs”, so the information is in there, just not trivial to find.


Do you have any suggestions on how this could be improved?

This could just be a Task specific thing, since most other objects within the DSL do not inherit functionality from other DSL objects.

Ideally, with something like Jar there would be a quick link to the Zip DSL, and either directly or indirectly via the Zip DSL documentation to the Task DSL, so it’s easy to traverse all of the properties and methods that get inherited along the way.

Generally, when the DSL doesn’t provide what I know should be there for a method or property, I either click the link to the API documentation – which unfortunately, doesn’t always work so well when hitting the groovydoc at the moment when trying to find inherited properties/methods from Java classes – or I manually jump to the Task DSL documentation to see if the property/methods are there.


The problem is a little more insidious…

All of the ‘Task’ methods are implemented on ‘AbstractTask’, which is internal. Groovydoc completely ignores this while in the Javadoc the methods are shown:

groovydoc: http://www.gradle.org/docs/current/groovydoc/org/gradle/api/tasks/bundling/AbstractArchiveTask.html javadoc: http://www.gradle.org/docs/current/javadoc/org/gradle/api/tasks/bundling/AbstractArchiveTask.html

This is pretty painful. We’ve been talking with the Groovy folks about this and discussing ideas for a next generation Groovydoc.

In the meantime, I’ll see what we can do about the DSL ref.