ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Rob Oxspring" <roxspr...@imapmail.org>
Subject Re: Docs out of sync
Date Thu, 20 Jun 2002 12:42:15 GMT
----- Original Message -----
From: "Erik Hatcher" <jakarta-ant@ehatchersolutions.com>
To: "Ant Developers List" <ant-dev@jakarta.apache.org>
Sent: Thursday, June 20, 2002 10:39 AM
Subject: Docs out of sync


> ----- Original Message -----
> From: <stevel@apache.org>
> >   I've realised that we now have a synchronisation problem; as soon as
1.5
> goes out the door, we should really migrate to xdoc based docs ASAP.
>
> Yes, the more I've compared side-by-side the setters to our actual docs
the
> more I cringe.  We've got lots of issues in this realm where some
attributes
> exist in code but are not documented (this is on purpose in some cases).
We
> have cases where we are subclassing a task and then turn around and
> unsupport lots of its setters by throwing a BuildException in the setter -
> when what really should be done is refactor the common stuff out and allow
> subclasses to really be subclasses and not some weird partial support of
the
> parent functionality.
>
> After 1.5 we can really start comparing what xdocs generates and try out
the
> migration to it.
>
> The main dilemma is how to auto-generate or merge in the rich type of
> information we have in our HTML files where some attributes are allowed if
> others are specified and the complex interactions between attributes that
> exists in the code and is easily described in free-form text but not so
easy
> to auto-generate.

What are the options here then? a few spring to mind but we need to get them
out in the open if a proper decision is to be arrived at.

1) use a tag e.g. @ant.required to hold free form text much like the current
Requred column in the docs.  This could be paired up with some @ant.min and
@ant.max for any addX/addConfiguredX methods to indicate how many are
expected allowed.

2) We could have a regular expression per tag (class) specifying what the
valid options are like lots of command line programs do
e.g. Javadoc would be something along the lines of:
(sourcepath | sourcepathref | sourcefiles | <sourcepath>+ | <fileset>+ |
<packageset>+) (destdir | (doclet docletpath | docletpathref) ) [maxmemory]
[packagenames] [packageList] [(classpath | classpathref)] [(bootclasspath |
bootclasspathref)] ...
At worst this could just be pasted into the resulting docs, and at best
could be processed into a state similar to today's where the implications
would be transformed for each attribute's view point.  Not too sure how to
go about the transformation but feel sure it'd be possible given a bit of
thought.

3) In a similar fashion we could just attach a tag to each attribute that
express the implied conditions:
e.g. the doclet attr of javadoc would have something along the lines of:
@ant.ifpresent docletpath | docletpathref -- ie the one of these must be
present if doclet is to be allowed
@ant.ifmissing destdir -- ie destdir is required if doclet is missing
while a missing classpath would only imply anything if it was present:
@ant.ifpresent !classpathref
Again it should be easy to massage the information into some more readable
in the docs.

4) I really no nothing about it but would XSchema have any useful syntax
that we could steal?

In either 2 or 3 it would be best if the conditions also allowed values to
be specified so that, for example, java's execute condition could express
fork=yes rather than just that fork is present.

Any other options? anything that these options doesn't cope with?

Rob

>
>     Erik
>
>
>
> --
> To unsubscribe, e-mail:   <mailto:ant-dev-unsubscribe@jakarta.apache.org>
> For additional commands, e-mail: <mailto:ant-dev-help@jakarta.apache.org>
>
>
>



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


Mime
View raw message