4

I have multiple programmers contributing examples for javadocs and some examples contain comments formatted with

/*
 *
 */

When I put these examples into a javadoc comment, the comment close in the example closes the javadoc comment.

/**
 *
 * /*
 *  *
 *  */  <-- right here
 *
 */

Is there a proper way to handle this without telling everyone that they cannot write comments in this format?

5 Answers 5

10

Javadoc comments use html, so encode the / as an entity: &#47;

/**
 *
 * /*
 *  *
 *  *&#47;  <-- right here
 *
 */

Telling everyone not to put that kind of comment in their code examples might be easier.

0
3

In my opinion, if the code is not self-explanatory or at least simple enough to understand with a brief description, then the code should be refactored. It needs to be shorter, or the variables need to be more understandable, or the logic requires rethinking.

In any case, I don't believe there's a way around it, if you wanted to include an example then do not have any comments within that example. If you really must have comments, use the // notation.

0

Why would you want to put commented source code into a comment?

This sounds like there's something wrong with your design if something like that is necessary.

1
  • Displaying example code in your JavaDoc is one possibility, but the inner JavaDoc block should be html-escaped. Jul 1, 2014 at 17:36
0

HTML is allowed within Javadoc comments. Enclose the code in your comment within <code> or <pre> elements. For example:

/**
 * Outputs "Hello World" to the console.
 *
 * <code>System.out.println("Hello World");</code>
 */
0

"/* */" comments cannot be nested. "//" comments can be, but they're only effective until the end of the line they start on.

Generally speaking, it's not a good thing to be including actual code in the JavaDocs - for one thing, they should be more abstract (the "why" of things instead of the "how").

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.