How to quote "*/" in JavaDocs

Question

I have a need to include */ in my JavaDoc comment. The problem is that this is also the same sequence for closing a comment. What the proper way to quote/escape this?

Example:

/**  * Returns true if the specified string contains "*/".  */ public boolean containsSpecialSequence(String str) 

Follow up: It appears I can use / for the slash. The only downside is that this isn't all that readable when viewing the code directly in a text editor.

/**  * Returns true if the specified string contains "*/".  */ 

Answer 1

Use HTML escaping.

So in your example:

/**  * Returns true if the specified string contains "*/".  */ public boolean containsSpecialSequence(String str) 

/ escapes as a "/" character.

Javadoc should insert the escaped sequence unmolested into the HTML it generates, and that should render as "*/" in your browser.

If you want to be very careful, you could escape both characters: */ translates to */

Edit:

Follow up: It appears I can use / for the slash. The only downside is that this isn't all that readable when view the code directly.

So? The point isn't for your code to be readable, the point is for your code documentation to be readable. Most Javadoc comments embed complex HTML for explaination. Hell, C#'s equivalent offers a complete XML tag library. I've seen some pretty intricate structures in there, let me tell you.

Edit 2: If it bothers you too much, you might embed a non-javadoc inline comment that explains the encoding:

/**  * Returns true if the specified string contains "*/".  */ // returns true if the specified string contains "*/" public boolean containsSpecialSequence(String str)