ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stefan Bodewig <bode...@apache.org>
Subject <javadoc>'s packagenames attribute
Date Tue, 21 Feb 2006 04:43:01 GMT
Hi all,

you can tell javadoc what to document by passing in either package
names or source files.  Our task supports both notions and provides
several options to specify the packages, the most common one is to
state where the source hierarchy is and explicitly provide patterns
that match the packages we want to document.

The way it works is that each pattern is turned into an include
pattern for a DirSet and then each directory given as source path is
scanned (and matched directories translated into package names).

If no patterns have been specified, the task won't scan any
directories at all.

The docs say the packagenames attribute is optional - since you only
need to specify it if you really point to the source tree rather than
the source files themselves.

This leads to the situation that if you point to your source tree and
don't provide any patterns for packages, Ant will claim you hadn't
specified any sources or packages at all.  This has been that way
since, well, ever.

I think we could do better and at least one person filing a bug
reports seems to agree.  The options I see:

(1) better document that package patterns are required if you only
point to the source hierarchy.  This is the fully backwards compatible
option.

(2) If no patterns have been specified at all, implicitly assume
packagenames="*" and match all packages that have been found.  This is
not backwards compatible since builds that have been breaking prior to
that change would suddenly start building.

I don't see much danger in this type of backwards incompatibility (and
thus prefer option 2) but wanted to gather some feedback before
enabling it.

Stefan

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org


Mime
View raw message