ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Steve Loughran <ste...@apache.org>
Subject Re: a few questions (sorry quite long)
Date Tue, 01 Mar 2005 10:32:57 GMT
James Fuller wrote:
> 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: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org


Mime
View raw message