Win a copy of The Little Book of Impediments (e-book only) this week in the Agile and Other Processes forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

NX:how to inlude a link to another package in Javadoc

 
Ulrich Heeger
Ranch Hand
Posts: 266
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi everyone,
I have a question concerning the @see tag in Javadoc.
How can I write a link to a class of another package:

If I use the javadoc-tool with following console statement:

I got only links to classes of the same package.
If I add:

then I got also the links to classes of the suncertify.remote package.
But javadoc will also write another folder called src-html.
Is this the only way to get the link to classes of other packages or does another alternative exist?
Thanks in advance
Ulrich
 
Nathaniel Stoddard
Ranch Hand
Posts: 1258
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
{@link java.lang.String}
See the javadocs docs.
 
George Marinkovich
Ranch Hand
Posts: 619
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Ulrich,
I recommend that you create all your javadoc at one time. This link explains how:
Topic: Documentation Question
 
Ulrich Heeger
Ranch Hand
Posts: 266
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Nathaniel, hi Georges,
thank your for the usefull links.
I have one more general question:
Do you guys use the Check Doclet - tool of Sun to verify your doc-comments?
Georges,
in the thread you linked to above, you recommend to write a overview.html.
Do you use a certain template for this html-file?
Thanks a lot in advance,
Ulrich
 
George Marinkovich
Ranch Hand
Posts: 619
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Ulrich,
Originally posted by Ulrich Heeger:
I have one more general question:
Do you guys use the Check Doclet - tool of Sun to verify your doc-comments?

Yes I like DocCheck, but StyleCheck might be even better. Details here:
Topic: Coding Standards

Georges,
in the thread you linked to above, you recommend to write a overview.html.
Do you use a certain template for this html-file?

No template. Basically the overview just describes your package structure.

Here's the start of my overview.html file:

<body>
The three top level packages correspond to three conceptual layers: {@link suncertify.db} handles all interaction with the database, {@link suncertify.remote} ...
s.
</body>
 
Ulrich Heeger
Ranch Hand
Posts: 266
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi George,
thank you very much for your help.
Greetings
Ulrich
 
Ulrich Heeger
Ranch Hand
Posts: 266
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi George,
sorry, but I have one more question.
When I write a package.html file for a certain package, DocCheck gives me following warning:

I don't know what to write within this tag, thus I've omitted it.
Can you give me an advice?
Thanks in advance & greetings
Ulrich
 
George Marinkovich
Ranch Hand
Posts: 619
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Ulrich,
Use the @since tag
package.html file
======================
<body>
Blah, blah, blah...
@since 1.0
</body>
but then use the -nosince javadoc switch
options file
=====================
-classpath scjd/classes
-d scjd/docs
-overview scjd/code/suncertify/overview.html
-sourcepath scjd/code
-nosince
This makes DocCheck happy.
 
Ulrich Heeger
Ranch Hand
Posts: 266
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi George,
it seems like you alway have an answer, thank you.
Do you think that it is generally tolerable to omit the @since tag in the package.html?
Thanks
Ulrich
 
George Marinkovich
Ranch Hand
Posts: 619
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Ulrich,
Originally posted by Ulrich Heeger:
Do you think that it is generally tolerable to omit the @since tag in the package.html?

Yes that's perfectly fine. I just mentioned it as a way to make DocCheck happy. You could reasonably come to the conclusion that on this particular point DocCheck will just have to remain a wee bit unhappy.
I think the purpose of the @since tag is to allow the developer to state at which point (that is, for which version) a feature was introduced into the code. For example, it might be useful in the Java API to know in which version of the JDK a particular feature became available. So the javadoc for the java.util.regex package uses a since tag to indicate that this feature has been available since Java 1.4.
So, my "@since 1.0" actually makes some sense. It's just saying that this package (suncertify.db) has been around since version 1.0 of the software. Is this really very useful information in the context of the project? Hardly. Should you feel bad about not using the @since tag? Not at all.
 
Ulrich Heeger
Ranch Hand
Posts: 266
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi George,
thank you once more for your really helpful comments.
Have a nice weekend, I hope I don't bother you once more this weekend
Greetings
Ulrich
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic