Two Laptop Bag*
The moose likes Developer Certification (SCJD/OCMJD) and the fly likes JavaDoc <code> or link? Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login
JavaRanch » Java Forums » Certification » Developer Certification (SCJD/OCMJD)
Bookmark "JavaDoc <code> or link?" Watch "JavaDoc <code> or link?" New topic
Author

JavaDoc <code> or link?

Chris Bicnal
Ranch Hand

Joined: Aug 17, 2005
Posts: 80
    
    1
Guys,

I'm finishing off my assignment and tidying up my JavaDoc. I've got a question for everyone out there though - how have you all formatted your JavaDoc comments?

I'm torn between using <code> and {@ } when referring to other classes in my comments. For example, I could reference JPanel by either <code>JPanel</code> which would put it in a different font or use {@ JPanel} which would provide a link to the JPanel JavaDoc page.

What have you guys done? When have you used <code> and {@ }? What do you recommend?

Thanks!

Chris
Roberto Perillo
Bartender

Joined: Dec 28, 2007
Posts: 2266
    
    3

Howdy, champ!

What I usually do is, if it's really important to see the other class in order to know or understand an API, then I use a link, otherwise I just use <code>. Also, if I use a link, I just use it the first time I mention the class in the text; the subsequent times, I use <code>. You may also consider using @see, and just use <code>... this is really a matter of choice.


Cheers, Bob "John Lennon" Perillo
SCJP, SCWCD, SCJD, SCBCD - Daileon: A Tool for Enabling Domain Annotations
Roel De Nijs
Bartender

Joined: Jul 19, 2004
Posts: 5456
    
  13

Roberto Perillo wrote:Also, if I use a link, I just use it the first time I mention the class in the text; the subsequent times, I use <code>.

I did it just like that. And I also used code-tags around null, true and false.

Kind regards,
Roel


SCJA, SCJP (1.4 | 5.0 | 6.0), SCJD
http://www.javaroe.be/
Roberto Perillo
Bartender

Joined: Dec 28, 2007
Posts: 2266
    
    3

Roel De Nijs wrote:And I also used code-tags around null, true and false.


Me too!
Roel De Nijs
Bartender

Joined: Jul 19, 2004
Posts: 5456
    
  13

Roberto Perillo wrote:Me too!

You know what they say about great minds
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: JavaDoc <code> or link?