's packagenames attribute

[Stefan Bodewig <bo...@apache.org>]

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

Re: 's packagenames attribute

[Peter Reilly <pe...@gmail.com>]

+1 for option 2.

Peter

On 2/21/06, Stefan Bodewig <bo...@apache.org> wrote:
>
> 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
>
>

Re: 's packagenames attribute

[Antoine Levy-Lambert <an...@gmx.de>]

----- Original Message ----- 
From: "Matt Benson" <gu...@yahoo.com>
To: "Ant Developers List" <de...@ant.apache.org>
Sent: Tuesday, February 21, 2006 3:54 PM
Subject: Re: <javadoc>'s packagenames attribute


[SNIP]
> I agree--my interpretation of backwards-compatibility
> is that working builds do not break; it is entirely
> permissible to make broken builds work.  I can think
> of examples where we have added a default value so
> that what was once a BuildException due to some
> missing attr/element is now legal... the worst that
> could happen is that a build generates more doc than
> it used to, and that probably presumes the use of
> <try>... i.e. not realistic to assume anything working
> would be changed at all, much less negatively.
> 
> -Matt
I agree too,

Antoine

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

Re: 's packagenames attribute

[Matt Benson <gu...@yahoo.com>]

--- Kev Jackson <ke...@it.fts-vn.com> wrote:
[SNIP]
(Stefan:)
> >(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.
> >
> >  
> >
> At the moment, this is a relatively minor change -
> either set the 
> packagenames="*" as a default value, or change the
> current 
> checking/validation.
> 
> >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.
> >  

I agree--my interpretation of backwards-compatibility
is that working builds do not break; it is entirely
permissible to make broken builds work.  I can think
of examples where we have added a default value so
that what was once a BuildException due to some
missing attr/element is now legal... the worst that
could happen is that a build generates more doc than
it used to, and that probably presumes the use of
<try>... i.e. not realistic to assume anything working
would be changed at all, much less negatively.

-Matt
> >
> If broken builds start building, do you actually
> think we'll get hassle 
> from people seeing different behaviour than
> expected/documented?  
> Technically it's a BWC problem, but in reality its
> relaxing the 
> restrictions and I think that we should do this to
> make peoples lives 
> easier (have to type less)
> 
> my 2p
> 
> Kev
> 
>
---------------------------------------------------------------------
> To unsubscribe, e-mail:
> dev-unsubscribe@ant.apache.org
> For additional commands, e-mail:
> dev-help@ant.apache.org
> 
> 


__________________________________________________
Do You Yahoo!?
Tired of spam?  Yahoo! Mail has the best spam protection around 
http://mail.yahoo.com 

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

Re: 's packagenames attribute

[Kev Jackson <ke...@it.fts-vn.com>]

>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.
>
>  
>
I think that if there are any changes, updating the doc to let people 
know that the default (old behaviour) is that the package name is expected

>(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.
>
>  
>
At the moment, this is a relatively minor change - either set the 
packagenames="*" as a default value, or change the current 
checking/validation.

>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.
>  
>
If broken builds start building, do you actually think we'll get hassle 
from people seeing different behaviour than expected/documented?  
Technically it's a BWC problem, but in reality its relaxing the 
restrictions and I think that we should do this to make peoples lives 
easier (have to type less)

my 2p

Kev

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