Javadoc Limitations
Can anyone explain to me why Javadoc is so limited compared to Doxygen? I come from C++ background and I am relatively new to Java so maybe I am missing something here?
My issues with Javadoc are as follows:
1) Why do I have to type explicitly {@link} tags? Doxygen will pick-up code references automatically and is smart enough not to produce duplicate links within the same comment.
2) Why do I have to use HTML for simple editing? I think it's ludicrous that I need to pollute my code with HTML paragraph tags - Javadoc could very easily interpret an empty line as the start of a paragraph like Doxygen does.
3) Why doesn't Javadoc produce class graphs? I realise there are 3rd party doclets/plugins/tools that do this but they aren't part of standard Javadoc. Doxygen will automatically produce class inheritance and collaboration charts for every documented class. It also provides a very nice class overview class diagram.
4) There is no 4 - I have many more gripes but I have mentioned enough to get my point across.
While I do have the option of using Doxygen for documenting my Java source code, I'd prefer to stick with the standard and even if I did switch I doubt my collages would approve.
The ultimate point of this post is to determine whether these features are missing due to some Java philosophy or design decision. I am already assuming the insistence of paragraph tags is something to do with some grand philosophy to embrace HTML - is that true?
[1604 byte] By [
pdrummonda] at [2007-10-2 22:22:08]
Hi,
My opinion is that Javadoc, on the contrary to what you say (and how lots of other automatic-documenting systems are implemented), offers the pretty nice solutions about everything.
About using of embedded HTML tags in Javadoc comments. If you do wish to format the comments, insert images and so on, so that to produce a more or less professionally looking documentation, I believe, using HTML is the only way possible. (Otherwise, you would have to invent your own formatting markup language and "pollute" with it those comments, which won't be anything better!)
Also, I believe, it would be a pretty bad idea to have a Javadoc tool to do lots formatting stuff automatically when you did not ever ask it to. I mean interpreting those new lines with paragraphs, automatically generating hyperlinks for everything the program "thinks" may be a hyperlink and so on. Even being implemented in a very good way, that would enforce everyone to follow the same formatting layouts and rules, which far not everyone needs (and for some even render the whole thing simply useless, because they have their own special standards on how their documentation must look).
However, Javadoc does provide a solution for your idea. Just write your own doclet! That doclet would do automatically every stuff you want, and when you are lucky and have implemented good thing, you may attract a lot of users! (But never every Javadoc user, of course.)
Concerning, having Javadoc to generate class graphs (and other UML diagrams), I believe, it might be good to have a special doclet doing this. But it will never be good to enforce that stuff to everyone. Far not everybody needs this, first. Moreover, generating any diagrams is a very very special thing. There's no any universal and obviously best solution about this. Attaching that stuff to Javadoc, would inevitably overburden the Javadoc (as well as the whole Java) development team, and at some point will end up having Javadoc look obsolete when someone else outside Sun would invent/develop something radically better than this.
That's actually why it is a dead end to get a company (even as big as Sun) to try to do/implement everything by themselves. It is never possible to concentrate in a single company every best minds in the world. Trying to do so will eventually end up in the stagnation and possible collapse of that company!
Much better way is to make your stuff open for enhancements by everyone. They will enrich your product with their own ideas and their things and in such a way keep you yourself always on the top and relevant for everyone.
That's probably what Sun does with Java as the whole and with Javadoc in particular. I love it!
Regards,
Leonid Rudy
http://www.docflex.com
Thanks for your comments. I beleive you should give doxygen a try - you can download, install and build the docs for a java project in about 10 minutes and you will see how professional it looks with extremely minimal effort from the developer.
leonid_rudy said:
[This] would enforce everyone to follow the same formatting layouts and rules
I'm not sure I understand your point here. What does automatic hyperlinks and automatic paragraphs force on the user other than saving them some extra work? Believe me, doxygen is the proof here. It just works.
Regarding class graphs, Doxygen provides the option to generate them which can be switched on or off so there is always the choice. Javadoc may provide doclets but there is no standard support, no standard specification for them. Otherwise, the Java API would include class diagrams.
Regarding custom doclets, it concerns me that none already exist for this purpose! I would certainly be interested in implementing one but I would be very suprised to learn I am the first to recognise these limitations! Maybe the Java community has yet to learn about the excellence of doxygen?
You know, everyone here has his/her own pet tools. I only happy it's really so and we may enjoy this. Much worse would be having the only one choice of something "standard" offered by some big and fat guy. You like doxygen, use it!
> I'm not sure I understand your point here...
My point is that not everyone needs this. (I don't need this, for instance).
If a certain algorithm picks the identifiers and names from the comments and generates for them hyperlinks, it's not necessary needed everywhere. It may not be needed within a source code citation, for instance. Further, on the contrary, one may need, indeed, to generate a hyperlink to a method or a class from some a name or text other than the method's or class' identifier. How are you going to do this without those {@link} tags or something like it?
Further, if you are to format your comments with something more than paragraphs and hyperlinks (e.g. showing something with italic or bold, or even more -- formatting with bulleted lists, tables and so on) how are you going to do this without HTML? But once embedded HTML is supported, what's the problem about
tags then?
You may support both approaches simultaneously, of course: some auto-formatting things and explicitly specifying HTML or {@link} tags. But when you do so, you must immediately introduced options to switch on/off all those auto-formatting features: an option for every such a feature, by the way! When you go on in that direction further and further, you will end up having a tool with options and switches controlling numerous petty things, which few will eventually bother to understand and use...
> Regarding class graphs [...] Javadoc may provide doclets but there is no standard support, no standard specification for them.
There may not be anything "standard" about this (and must not be!) Non-standard, proprietary implementations do exist. Just look at http://www.doclet.com for instance. If you don't like they are not for free, I can say, it is not easy to develop such things... someone has to pay all the bills!
> Regarding custom doclets, it concerns me that none already exist for this purpose! [...] Maybe the Java community has yet to learn about the excellence of doxygen?
Maybe... Just do it and teach us all!
;-)
Regards,
Leonid Rudy
http://www.docflex.com
Sorry for the late reply! When I read your last post I decided to have a nice old rant on my blog about this. Take a look: http://gushieblog.blogspot.com/2006/06/doxygen-versus-javadoc.html and let me know what you think!
Hello,
I've been trying to find out if DOXYGEN can read a directory containing C/C++ source code and output a copy of that source code to a new directory and where the copy of the code will also contain hyperlinks to key references throughout that new directory?
Xref-tech has this feature for JAVA code and it's free, and it also this capability for C++, but the C++ version is fairly expensive!
Can anyone tell me if DOXYGEN has this capability? I looked through some of their website examples and didn't see any examples of this particular capability!
Thanks very much!
BobK
