Sample code in javadoc comment

Question

I have some programmers who give examples for javadocs, and some examples contain comments formatted with

/* * */ 

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

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

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

Answer 1

Javadoc comments use html, so encode / as an object: /

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

Saying that everyone who has not commented on their code examples can be easier.

Answer 2

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

In any case, I don’t think there is a way around this if you want to include an example and then you will not have comments in this example. If you really have comments, use the // notation.

Answer 3

Why do you want to put a comment in the source code in a comment?

It is like something is wrong with your design if something like that is necessary.

Answer 4

HTML is allowed in Javadoc comments. Add code to your comment within the <code> or <pre> elements. For instance:

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

Answer 5

"/ * * /" comments cannot be nested. Comments "//" may be, but they are valid only until the end of the line on which they begin.

Generally speaking, it is not good to include actual code in JavaDocs - firstly, they should be more abstract (“why” of things, not “how”).