commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From robert burrell donkin <robertburrelldon...@blueyonder.co.uk>
Subject Re: [digester] patch: usage examples
Date Tue, 19 Aug 2003 20:11:35 GMT
On Friday, August 15, 2003, at 03:38 AM, Simon Kitching wrote:

> On Fri, 2003-08-15 at 06:32, robert burrell donkin wrote:
>> committed. many thanks.
>>
>> it all looks fine. i've managed to resist the temptation to tinker too
>> much (just yet ;) but i have renamed the directory from example1 to
>> addressbook since i prefer descriptive names where possible. (i think 
>> that
>> it makes it easier for users.)
>
> Tweak away :-) Any improvements to the examples are welcome; I would be
> keen to see better ways of implementing the "addressbook" example.
>
> I should have explained why I picked the name "example1"; it was chosen
> so that we could also have example2, example3, etc.
>
> Example 1 is the "start here" point, showing the simplest features of
> Digester.
>
> I had intended to add an Example 2 with more complex things like:
>   * passing Digester as a SAXContentHandler to an existing SAXParser
>     instead of calling parse(File), as done in example 1
>   * demonstrating ObjectFactoryRule
>   * wildcards in patterns
>
> And maybe example 3 getting on to really tricky stuff like:
>   * extended rules matching
>   * NodeCreateRule (if I can figure it out myself :-)
>   * subclassing the Digester
>   * handling namespaces

that sounds great.

> If you want to name the examples by the example filetype they happen to
> process, then I suggest the readme file be modified to indicate which
> order a newbie to Digester should read the examples in.

what i'd really like to do is to integrate the examples into a set of html 
documents which can be posted on the site and browsed. i know that this is 
quite a long way off at the moment but it's nive to dream :)

i prefer examples with names since it's easier to remember which is which 
when answering user questions. we should certainly make sure that the 
(maybe something like the descriptions you've given about would be cool in 
the readme).

>> don't worry too much about the build script, it not a priority. maybe it'
>> d
>> be a good idea to have a separate build.xml script in the examples
>> directory.
>
> I just want to make sure that changes in Digester itself don't break the
> examples. It would be rather embarrassing to ship a digester release
> where the examples don't compile. To avoid this, I suggest that the
> examples be *compiled* as part of the "dist" target, though of course
> the resulting class files shouldn't be included in the distribution jar!

+1

> That way, any time someone runs "ant dist", they immediately see if the
> examples are broken or not. Agreed, they don't know if the examples
> still *work*; that would require them to be written as "unit tests",
> which unfortunately then makes them less useful as tutorials (too much
> unit-test-related clutter).

it might be nice to have a few example unit tests as part of the examples.
  there are some tricks such as using a StringReader (rather than reading 
the xml from a file) which people might find useful.

> Or we could build them whenever the unit tests are built? I don't think
> that the Digester unit tests are in a very good state though (I was
> going to look into this soon, as I also need to build unit tests for the
> Plugins module).

the digester unit tests may not look pretty but they have provided pretty 
effective. i'm particularly guilty since i tend to leave a lot of 
commented out logging in there.

- robert


Mime
View raw message