Shared comments
I seem to end up duplicating a lot of text, especially between getters and setters and property members. I can always use the {@link} syntax but this can lead to a paper trail for the user to find the info they need, and they don't work so well when your javadoc is presented by Eclipse as a tool tip. It would be nice if Javadoc could share parts of a definition.
My suggestion is to have{@export name text} that could (for example) be used in the javadoc for a private member variable. This could then be referenced from the public getter and setter using an{@import member-reference name} tag.
publicclass MyClass{
/**
* {@export def My long and rambling definition of the myProperty property}.
* Some other private implementation details I do not want exported.
*/
privateint myProperty
/**
* {@import #myProperty def}
*/
publicvoid setMyProperty(int myProperty){
this.myProperty = myProperty;
}
/**
* {@import #myProperty def}
*/
publicint getMyProperty(){
return myProperty;
}
}
Hello Reg Whitton,
Both you messages (this and http://forum.java.sun.com/thread.jspa?threadID=751443) are interesting to me.
I believe, such things cannot be resolved directly using the standard means provided in Javadoc. Actually, both problems require certain special processing of custom inline tags, and you can do this by writing you own doclet.
However, writing an entire doclet from scratch of the quality equal to the standard one is an immense work (especially, when all you actually need is to add a few extra lines).
I suggest to look at the tool called DocFlex/Javadoc: http://www.filigris.com/products/docflex_javadoc/
This is a template-driven doclet. It generates the Java API HTML documentation of the quality comparable to that of the standard doclet. It also generates an excellent RTF documentation (which the standard doclet doesn't). Most important, this tool allows easily programming all such little extra things as those you are asking here. It was specifically designed for this!
If you are not afraid of using new original technologies not necessary coming under the famous brands, I believe, this tool might be immensely helpful for you!
If you have any more questions, I'm happy to explain everything.
Regards,
Leonid Rudy
http://www.docflex.com
Thanks Guys.
I sort of guessed there currently wasn't anyway of doing this with the standard doclet, but I had to post this and http://forum.java.sun.com/thread.jspa?threadID=751443 just to get it out my system. They have niggled me for sometime.
Doug,
I have now finished my big Javadoc sweep , but I would still be interested in submitting the idea for inclusion in future. However, when I look at the JCP site it isn't obvious to me how put ideas forward. Can you give me a clue?
Reg
