btw I have a few general developer questions... before I start caning bugzilla I think any responses would be well appreciated;
-------------------------------- 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>
This makes some sense, apart from the schema bit at the bottom. Schema? We dont need no schema :)
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.
RDF? RDF and Schema ?:)
Actually I like the suggestion to an extent - code is often the wrong place to put metadata. But as most of the attributes of a task can be determined through introspection, i think xdoclet does have something to say.
One thing we need to be able to describe is the situation when one of a set of attributes is needed. required being true/false is not enough.
----------------------------------------- a few general comments ----------------------------------------
- getlibraries has no task definition that I can see....correct me if I am wrong
<libraries>
- does scriptdef have namespace capability
- i think its important to make sure developers for for DispatchTask...its seems to be buried
hadnt seen it myself
- note: there is no 2005 copyright in ant manual/docs
should appear in edited files
- is there a list of @ant.task category types anywhere ?
nope
- is abstractaccess optional task @ant.task category the right way to use this doc tag? also any list of ant.task category anywhere ?
nope. remember the @ant tasks were a quick draft in 2002; we dont need to stick to them.
- couldnt find any logging/listener tests under testcases ?
probably arent any then :(
- MagicNames.java...whats the status and intended purpose ?
Looks like it is intended to be a central repository of magic properties.
- any update on webdav task
We arent doing one.
-------------------------------------------- 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 ?
We cant move things. If you move stuff, you have to leave a facade class there. Why? Because we dont know who has subclassed or reused a class. A lot of people use ant programatically as well as in the XML layer, and we need to keep the effective API as stable as the XML language. This is precisely why we are org.apache.tools.Ant
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
Launcher is special; it is its own JAR file, and has to locate and launch ant proper. it must be 100% self-contained.
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
I think they did come from other projects, and are designed for reuse outside ant.
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 ?
No, except we know that they are there. One for types, one for tasks, one for listeners.
-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
maybe because the things they test are at that level.
- 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.
yes, there is lot of historical stuff. Eventually we will be crushed by the weight of backwards compatiblity.
I have just updated the ant_task_guidelines doc in the repository, please take a look at this and see if it clarifies things.
-steve
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
