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?
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.
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.
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>
*/
Javadoc comments use html, so encode the / as an entity: /
/**
*
* /*
* *
* */ <-- right here
*
*/
Telling everyone not to put that kind of comment in their code examples might be easier.
"/* */" 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").