64

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 "*/".
 */
Steve Kuo
  • 61,876
  • 75
  • 195
  • 257
  • 2
    I like bobince's suggestion to include "asterisk followed by a slash", perhaps in parentheses after the literal "*/". It's then readable both in code and Javadoc. – ide Nov 14 '10 at 22:38

6 Answers6

48

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)
jfs
  • 399,953
  • 195
  • 994
  • 1,670
Randolpho
  • 55,384
  • 17
  • 145
  • 179
  • 2
    I'd have gone for the B. – Tom Hawtin - tackline Mar 10 '09 at 19:17
  • 3
    Does this bother anyone else except for me? Now it looks good in the javadoc but it's unreadable when you're just looking at the source code... – Tim Frey Mar 10 '09 at 19:24
  • 2
    It's not entirely unreadable. You're a programmer, right? You should at least be able to realize that it's an HTML escape code, even if you don't recognize the actual value. You can always look it up. As I said before, the point of javadoc is readability of documentation, not code. – Randolpho Mar 10 '09 at 19:27
  • That said, you could always embed a comment that's not Javadoc to explain it to yourself elsewhere in your code. Something like: // searches for "*/" – Randolpho Mar 10 '09 at 19:27
  • 1
    Just open the javadoc view in your IDE. They tend to be pretty awesome these days... – Stephen Mar 10 '09 at 19:58
  • One note that may be mentioned is that this will not get escaped in `{@code }` blocks and if a code or pre-formatted output is desired that it must exist within a `` block instead. – Brett Ryan Aug 12 '16 at 01:42
16

Nobody mentioned {@literal}. This is another way to go:

/**
 * Returns true if the specified string contains "*{@literal /}".
 */

Unfortunately you cannot escape */ at a time. With some drawbacks, this also fixes:

The only downside is that this isn't all that readable when viewing the code directly in a text editor.

Lyubomyr Shaydariv
  • 20,327
  • 12
  • 64
  • 105
9
/**
 * Returns true if the specified string contains "*/".
 */

This is the ‘right’ solution, but for readability's sake I'd probably go for:

/**
 * Returns true if the string contains an asterisk followed by slash.
 */
bobince
  • 528,062
  • 107
  • 651
  • 834
  • 1
    well, ok, but that advice isn't very useful when giving examples of shell glob patterns e.g. `foo/bar/**/baz.zip` – Jason S Oct 17 '19 at 19:30
6

Use the entity 

*/

In your documentation it will show up as a "*/"

cpatrick
  • 4,446
  • 4
  • 18
  • 11
6

Another way I stumbled upon, just for completeness: add some HTML markup which doesn't alter the output between the * and /. 

  /**
   * *<b/>/
   */

Compared to the HTML escape solution, this seems something of an ugly hack, but it also yields the right result in HTML output.

Jonik
  • 80,077
  • 70
  • 264
  • 372
  • 1
    Not quite; your suggestion as it currently stands would likely violate html doctypes. If somebody were to go this route, I would suggest something like: */ to make sure the tags are closed. – Randolpho Mar 10 '09 at 19:58
  • Ah, I was wondering about that, but left it like that because it's the shortest option and worked fine in IDEA (Ctrl-Q). If not , wouldn't */ or */ suffice? – Jonik Mar 10 '09 at 20:09
6

I would suggest you also add a line comment somewhere near saying something like

// *&#47; is html for */
hasen
  • 161,647
  • 65
  • 194
  • 231