On Sat, Apr 24, 2010 at 9:55 AM, Russel Winder <[email protected]> wrote:
> On Sat, 2010-04-24 at 09:20 +0200, Hans Dockter wrote: > > > > On Sat, Apr 24, 2010 at 8:47 AM, Russel Winder <[email protected]> > > wrote: > > On Sat, 2010-04-24 at 07:45 +0100, Russel Winder wrote: > > > I suspect that there are a couple of missing options from > > the JavaDoc > > > task. > > > > > > options.source ( . . . ) > > > options.header ( . . . ) > > > > > > don't seem to work. > > > > > > Sorry, should have added: > > > > options.excludePackageNames ( . . . ) > > > > Have a look at the Javadoc of the Javadoc task. There you can see how > > to exclude things and set the sources. The userguide provides a link > > to this Javadoc. > > Much of the time it is not entirely clear how to interpret the JavaDoc > (which is often completely uncommented, as in this case) to deduce or > infer a usage in a Gradle script. Hence all the silly questions on the > email. > The SourceTask that is extended by the Javadoc task provides proper docs. > > All these are really just indicators as to how to improve the > documentation. When I try and look for quick answers to questions, I > often find myself having to take lengthy tours round the user guide and > the JavaDoc and GroovyDoc and undertake experiments. We need to check whether the Groovydoc is now good enough to replace the Javadoc, as it also includes the Java classes. That would make life easier. > The user guide is > a big document but somehow it seems structured for a different purpose > than the one I need to make of it most of the time. The mental model > behind the structure of the user guide doesn't seem to match what I need > of it. Current example is the jar task, which is part of the java > plugin but is part documented there, part documented in two or three > other places and I can't see why the structure is the way it is from a > user task model perspective. > I'm sure the structure of the user's guide can be improved. - Hans -- Hans Dockter Founder, Gradle http://www.gradle.org, http://twitter.com/gradleorg CEO, Gradle Inc. - Gradle Training, Support, Consulting http://www.gradle.biz > > Maybe I am an outlier. > > > > Could you file a Jira for the header. > > Done. GRADLE-921. http://jira.codehaus.org/browse/GRADLE-921 > > > BTW: We are aware that the API of the Javadoc task is more complicated > > then it needs to be at the moment. We will improve the usability for > > 1.0. > > > Splendid. There needs to be consistency between JavaDoc and GroovyDoc > as well. as both being simpler. > > > > -- > Russel. > > ============================================================================= > Dr Russel Winder t: +44 20 7585 2200 voip: > sip:[email protected] <sip%[email protected]> > 41 Buckmaster Road m: +44 7770 465 077 xmpp: [email protected] > London SW11 1EN, UK w: www.russel.org.uk skype: russel_winder >
