Feature Requests item #518777, was opened at 2002-02-17 07:39 You can respond by visiting: http://sourceforge.net/tracker/?func=detail&atid=402707&aid=518777&group_id=31602
Category: None Group: None >Status: Closed Priority: 5 Submitted By: Vincent Massol (vmassol) Assigned to: Nobody/Anonymous (nobody) Summary: Test XDoclet Initial Comment: Hi, Thanks for that great tool. Here is the XDoclet that I'd like to develop for Cactus (http://jakarta.apache.org/cactus), a unit testing framework for server-side java code : * Create a "@test <unit test class name - same format as @see>" javadoc tag * Have a XDoclet that would read this and add the unit test _source_ code to the documentation for that class, i.e. in the javadoc of the method/class, there would be a link to the source test. Incentive: The main idea is that unit test provide a good way to document code as provide samples of how to use a given method. Usually, existing javadoc is missing badly examples in the javadoc comments. Doing it the way I described it would bring 2 advantages : 1/ You have a suite of unit test for your code that is always up to date (you run them often in the XP way of course) 2/ You have associated documentation with examples that are always working ! Question/Feature request : * Is it possible to do with XDoclet ? Notably, is there an API to get the _source_ code ? Thanks -Vincent ---------------------------------------------------------------------- >Comment By: Vincent Massol (vmassol) Date: 2002-02-20 15:18 Message: Logged In: YES user_id=22169 Thanks Steven, Yes, you're right, this initial "feature request" is transforming itself into a discussion and this is not the place. I'm closing it and will have a look a xjavadocs. Thanks -Vincent ---------------------------------------------------------------------- Comment By: Andrew Stevens (stevensa) Date: 2002-02-20 14:54 Message: Logged In: YES user_id=247081 To address your first point, XDoclet will quite happily create HTML, and in fact does so for its own template tag documentation and Todo lists (which are generated by the DocumentTags and Info subtasks of the DocumentDoclet task respectively). All it needs is an HTML file for the template, with XDoclet tags included at various points. You probably *could* use XDoclet to achieve your aim, but you'd need to: - write a custom tag handler that could look up the source code in the test suite for a given @test tag's value. - create a bunch of templates that mimic the javadoc output. - (possibly) create a custom subtask for <template> that processes each of your templates (or just use a separate <template> for each one). However, although it may be possible, this may not be the simplest solution. If all you want is an extended version of javadoc that handles the @test tags, then why not just take Sun's standard doclet and extend it? I've no idea how easy or otherwise this may be, since I've not tried it myself, but it may be it's a quicker solution. You'll still need to write something to extract the test suite's code, but you avoid having to do the templates etc. Of course, as usual there's plenty of other ways it might be done. I only really mentioned xjavadoc because I thought this might be a possibility for unit testing it - the javadocs for a set of classes are easily generated (there's even an Ant task for it), so if the output from an equivalent xjavadoc doclet wasn't identical, we'd know somebody broke something... As for your other points, Aslak can tell you what xjavadoc is and isn't better than I can, though the mailing lists might be a better place to discuss it since they're not feature requests as such. And yes, xjavadoc is in the xdoclet CVS - check out the 'xjavadoc' module. ---------------------------------------------------------------------- Comment By: Vincent Massol (vmassol) Date: 2002-02-20 13:08 Message: Logged In: YES user_id=22169 Steven and Aslak, First a big thank you for your extensive answers. There are still a few things I would like to clarify,. >From your comments, here is what I understand : 1/ Although XDoclet is a generic engine for transforming javadoc comments to any thing (source code, configuration files, HTML, etc), it is not geared towards producing HTML code, i.e. it doesn't help in this area. 2/ xjavadoc is a generic transformation engine that takes source code as input an can transform it in anything ? In other words, it is like javacc/antlr/etc but presents a higher level (and easier to use) API (more java oriented ?) to users ? Have you also considered using JavaML (http://www.cs.washington.edu/homes/gjb/JavaML/) to represent java source code as XML and then use XSLT (for example) or offer a JDOM API to access the source content ? Maybe it is not ready yet ? Once we've got that code into XML then the full world of possibilities opens up : - manipulations to transform into other things (HTML javadoc, web documentation of source code, the Test doclet I mentionned, etc) - tools like code conventions checkers, metrics. They do already exist, but it makes it much simpler to write them . Also it is then very easy to write a code formatter and let all the team have exactly the same formatting of the code. It seems to me that for the moment, none of all these tools are adapted to what I'm looking for but the javadoc tool is probably the closest. Anyway, it seems you have some very cool ideas and I bet xjavadocs will be a success :-) BTW, is there any visible code for xjavadocs ? Is it in the xdoclet CVS ? Thanks for your help. -Vincent P.S.: Aslak, comment se fait-il que tu parles si bien francais ? Je suis curieux, comment as-tu devine que je suis francais ? ;-) ---------------------------------------------------------------------- Comment By: Aslak Helles�y (rinkrank) Date: 2002-02-20 07:41 Message: Logged In: YES user_id=49846 howdy, xjavadoc's API is very similar to the com.sun.javadoc API. The main difference is that you can mutate the javadoc contents and tags and do a save() on the class afterwards. - and it has built-in tag attribute parsing too, making the job easier for xdoclet. it would be possible to add a method called like this: XClass clazz = ... String doItCode = clazz.getMethod("doIt (java.io.Reader,int,java.lang.String)").getCode(); -And do whatever with the doItCode, for example stuff it in some report. add a feature request if you're sure you're gonna need it. xjavadoc has a way to use doclets (but not doclets written for classical javadoc, it's xjavadoc doclets), but there are no plans to write a doclet that would produce HTML API docs like javadoc. that's a fairly complicated task, and HTML generation is _not_ the reason why i wrote it. xjavadoc today is only the core engine that scans the code. i heard som rumours about the JDK 1.4 javadoc having better support for modifying the standard doclet's output, but i haven't checked. if that's true, maybe a hybrid javadoc/xjavadoc solution could be used to achieve vincent's goal? qu'est-ce que tu en penses vincent? -aslak ---------------------------------------------------------------------- Comment By: Andrew Stevens (stevensa) Date: 2002-02-20 05:54 Message: Logged In: YES user_id=247081 It seems to me that what you need is just a variation on the standard javadoc doclet, which in addition to the usual tags will also process the @test tags, e.g. adding a "test cases" section to the generated documentation. Of course, there's still the problem of reading the source of the test cases, but I guess there's parsers around that can do that (isn't that what xjavadoc is doing with javacc?) I'm not sure XDoclet itself is the answer, though. You don't want to generate new code based on a template, you just want the javadocs to include extra information. On the other hand, xjavadoc (being a replacement for javadoc) is a distinct possibility. Aslak, am I right in thinking xjavadoc has/will have a custom doclet API, like javadoc does? And if so, presumably we'll provide a "Standard" doclet that produces javadocs identical to Sun's (useful for testing xjavadoc, since we can run both over the samples and compare the output HTML files). In which case, perhaps we could do this FR as a sample custom doclet? ---------------------------------------------------------------------- Comment By: Vincent Massol (vmassol) Date: 2002-02-17 12:47 Message: Logged In: YES user_id=22169 Thanks Ara. It's not really about modifying a class but rather getting information about a class (including method source code snippets) and generating HTML (javadoc). I'm eagerly waiting for xjavadocs. Is there a place I can monitor its progress (or even help, if I find the time ;- )) ? CVS ? Thanks -Vincent ---------------------------------------------------------------------- Comment By: Nobody/Anonymous (nobody) Date: 2002-02-17 08:40 Message: Logged In: NO What you're describing is not yet possible. First AFAICS you want to modify a class, not generating a new class. That's not possible right now, you have to wait till another module we're working on (xjavadocs) is finished, you'll be able to modify classes and many other cool stuff! Also currently you can't get the source code body of a method or class or whatever, just the class structure. Again xjavadocs will make it possible. Ara. ---------------------------------------------------------------------- You can respond by visiting: http://sourceforge.net/tracker/?func=detail&atid=402707&aid=518777&group_id=31602 _______________________________________________ Xdoclet-devel mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/xdoclet-devel
