----- Original Message ----- From: "Erik Hatcher" <[EMAIL PROTECTED]> To: "Ant Developers List" <[EMAIL PROTECTED]> Sent: Thursday, June 20, 2002 10:39 AM Subject: Docs out of sync
> ----- Original Message ----- > From: <[EMAIL PROTECTED]> > > 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:[EMAIL PROTECTED]> > For additional commands, e-mail: <mailto:[EMAIL PROTECTED]> > > > -- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
