-------------------------------- a few comments on usage of XDoclet to autodoc manual --------------------------------
as someone who is a complete fan of XDoclet and avid user in enterprise java computing...I am surprised at myself at having reservations with its usage in task definitions having a single source from which documentation is generated is a 'good thing'...esp in defining task, its attributes, as well as general documentation, but how to deal with other potential documentation requirements, e.g. if we wanted to we could also embed build scripts, example input/output, and schema definitions as well...perhaps there is some traction to be gained by having a simple task markup language
without thinking....
<?xml version="1.0" encoding="UTF-8"?>
<task name="echo" xmlns:x="http://www.w3.org/1999/xhtml";>
<attribute name="message" required="true|false" default="">
<desc>the message to echo.</desc>
<required>Yes, unless data is included in a character section within this
element.</required>
</attribute>
<attribute name="file" required="true|false" default="">the file to write the message to.</attribute>
<attribute name="append" required="true|false" default="false">Append to an existing file?</attribute>
<attribute name="level" required="true|false" values="error,warning,inf,verbose,debug"
default="warning">Control the level at which this message is reported. One of "error",
"warning", "info", "verbose", "debug" </attribute>
<block name="description">
<x:p>Echoes a message to the current loggers and listeners which means System.out unless
overridden. A level can be specified, which controls at what logging level the message
is filtered at.</x:p>
<x:p>The task can also echo to a file, in which case the option to append rather than
overwrite the file is available, and the level option is ignored</x:p>
</block>
<usecase>
<!-- could place example build scripts, along with inputs/outputs/expected -->
</usecase>
<dependencies>
<!-- if we were smart we would have this in a <getlibraries/> friendly format -->
</dependencies>
<schema type="relaxng|dtd|xmlschema" href=""/>
</task>
we could use xinclude if we wanted to break things up....also we could assume that code takes precedent either overwriting, or where no source comments exist taken from this document for ant manual definition purposes...I really think given task writers the ability to combine the power XDoclet and and external task markup format.
Also this format could be impregnated with dublincore for versioning; in addition we could choose xhtml as an additional format...in any event the more meta data the better.
----------------------------------------- a few general comments ----------------------------------------
- getlibraries has no task definition that I can see....correct me if I am wrong
- exec task has floating html tag in manual
- does scriptdef have namespace capability
- i think its important to make sure developers for for DispatchTask...its seems to be buried
- note: there is no 2005 copyright in ant manual/docs
- is there a list of @ant.task category types anywhere ?
- is abstractaccess optional task @ant.task category the right way to use this doc tag? also any list of ant.task category anywhere ?
- couldnt find any logging/listener tests under testcases ?
- MagicNames.java...whats the status and intended purpose ?
- any update on webdav task
-------------------------------------------- some very boring and picky refactoring related thoughts --------------------------------------------
I see a lot of Ant refactoring opportunities with respect to package naming...no doubt the twin poles of maintaining backwards compatibility with cutting edge functionality has caused a bit of chaos in the source tree.
There are a few methods of mapping old package names (satisfy deprecated, older calls) to better logical structures...any thoughts re this ?
if so....then a few suggestions on moving things around;
Why not move things like -org/apache/tools/launch/Locator to -org/apache/tools/helper
Why not move -org/apache/tools/NoBannerLogger, SubBuildListener, XMLLogger to -org/apache/tools/listener
Why not move ?
-main/org/apache/tools/bzip
-main/org/apache/tools/bzip2
-main/org/apache/tools/mail
-main/org/apache/tools/tar
-main/org/apache/tools/zip
excuse my ignorance here (well if u never ask questions...)....are these are org.apache.tools packages used by other apache projects
Also in testcases things are a bit messy...for example why not put dummy into
-testcases/org/apache/tools/dummy
along these lines, I find burying property files can sometimes be detrimental, for example in main source we have;
-main/org/apache/tools/taskdef/defaults.properties
-main/org/apache/tools/types/defaults.properties
-main/org/apache/tools/listener/defaults.properties
is heritical to move these to somewhere more visible ?
-also quite a bit of property files scattered about testcases...might be useful to agree on some formalism here
perhaps we could prune -main.com.ice.tar -main.com.oreilly.servlet
- why are these tests at toplevel ? testcases/org/apache/tools/mail testcases/org/apache/tools/tar testcases/org/apache/tools/zip
- dont understand why dispatch has its own directory ?
many thx, and many apologies for my naive questions.....I know that (esp refactorings) there will be backward compatibility issues dominating the reasons why things exist.
regards, Jim Fuller
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
