Hello, Good suggestions, Peter.
Erik Hatcher wrote: > > ----- Original Message ----- > From: "Peter Donald" <[EMAIL PROTECTED]> > > > I was just playing around with the xdocs proposal and I have a few > requests ;) > > > > * Could you rename your templates to end with .j as that *seems* to be the > > standard that most other xdoclet templates use (though I could be wrong). > > Ummm, no! :) I don't like the .j extension. I have a feeling it was a > holdover from when XDoclet was EJBDoclet and it was designed to be .java > template. We aren't creating .java files - but a lot of XDoclet's builtin > stuff is. > > I prefer .template. A while ago when I went hunting for the XDoclet stuff in myrmidon, I had no idea that the files with .template were related to XDoclet. On the other hand if they were .j, I wouldn't have known either because I didn't know anything about XDoclet :) . Although .j may not be a very good convention, it is a convention nonetheless. > > * If someone was to create "summary" pages for each category of > > tasks/datatypes that listed all the types in that category and maybe gave > a > > blurb about category (blurb got via merge external xml operation?) then > that > > would be fantastic. > > Bill?? Yes. I was occupied tracking down a bug in jaxen which is used by dom4j which is used by DVSL. With that fixed, I'm now able to generate correctly formatted pages for the datatypes as well as tasks with only minor changes to the existing stylesheet. Now that this is working, I'll look at generating a tasks and datatypes overview page. > > * Rather than defaulting to "other" as catgory if it is undefined - > perhaps > > it would be a good idea to default to the last element in package name in > > which the task is contained. So tasks in > > > > o.a.t.a.taskdefs.optional.vss > > > > would be in the "vss" category if none other was specified. This would > make > > it much easier to also use code unchanged for ant2 ;) > > Thats a good idea! Perhaps we could have that as a configurable option what > the default category is. I'm not going to concern myself much with the > category stuff at the moment beside perhaps making this change because I > feel the most important thing is for us to get the generated documentation > as good as the current HTML documentation. Once there, we can then migrate > that proposal to the main code base. Then we can have a field day with > categories and other such features! I like the idea generally but because the XDoclet process doesn't know all the categories at any given time, I'd use the last two elements of the package to avoid collisions. So for optional tasks, they would go in optional/vss (to use your example) eliminating namespace collisions. This would also work better for third party tasks. Something I'm considering in the short run, is to ignore the categories and generate the XML (and respective HTML) in the same directory structure currently used. For the most part, the new doc would be a drop in replacement for the old. Links to ../CoreTypes, etc. everywhere would still work. The category meta info would still be used to generate an overview page but it would have nothing to do with the physical location of the files. What I'd really like is a way of specfying how tasks are classified into categories at the Ant task level much the way the <group> element works for javadoc or in an XML file. That allows much more flexibility in how things are organized over hard coding all categories in the @ant.task tag in each task source file. Which categories a task belongs to is strictly a documentation issue and not at all related to the behavior of the task. > > * Also it does not seem that nested elements are processed proeprly - or > am I > > missing something. ie Are top level elements and nested elements treated > > identically? ie will the structure of a nested element be fully documented > ? > > We're going to work on this. I haven't had a look at Ara's pointer to the > recursive templates, but will do so soon and likely integrate that (unless > Bill beats me to it) into our templates to have it recursively output nested > elements. We'll add some "stop" logic for it to cease the recursion when a > known datatype is found. Right. It's not yet recursing on sub elements. Will see what I can do to fix this. > > * Also it would be great to write the task so that only the changed files > are > > passed to the xdoclet engine. Because each file generates a separate xml > then > > this should not be a problem. > > I think we'd have problems when doing the element recusion then though - > we'd need all the classes in the XDoclet "model" when generating task > documentation. I think getting the dependency checking working well under most cases is rather important. If committers have to regenerate all the XML because of a little change to one task, it won't go over well. Initially, the task could handle dependency checking like the <style> or <dvsl> tasks where a newer source causes the respective target XML to be regenerated. But if the XDoclet template is newer, then everything is regenerated. Handling other dependencies such as changes to datatypes or source XML's could be done with <uptodate>. > > To generate the defaults.properties files you > > can post-process all the generated xml files to extract filenames as > > appropriate. This would allows us to have xdoclet fully integrated into > our > > buikld process with virtually no speed hit > > True - we'd need to capture the "ignore" flag into the XML files then > though, which we aren't currently. Yes, I'd considered that as well. The problem is both the <dvsl> and <style> tasks don't have a way to use a fileset is input with only a single file as output. I was considering fixing this in the <dvsl> task or even implementing support for a merge mapper. However, XDoclet already has all info for the classes loaded in memory so it's really quick to run another template to generate a single file like default.properties. I used the same technique to have XDoclet generate a single XML file listing all the tasks which I was then planning on using to generate a table of contents. Such an XML file could then be used for many different things where you wanted a listing of all tasks and datatypes. In the future, it could even replace default.properties :) . > I am also going to add the output of general (currently unrecognized) > "@ant." tags to the XML so that its extensible and grabs stuff without even > needing to know about it explicitly. This will allow us to drop special > tags in, have them appear in the XML, and then do what we want with them > later without having to modify the template. > > Erik Sounds good Erik. -Bill -- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
