Filesystem paths (Windows and Linux) in Javadoc

JavadocPaths.java

/**
  * Javadoc for filesystem path edge cases.
  *
  * <hr style="height:1px;border:0;border-top:1px solid #CCC">
  *
  * <h2><strong>Edge Case 0: Inline Windows Filesystem Paths</strong></h2>
  *
  * <p>Here is an inline Windows fs path with backslashes:
  * <code>"C:&#92;Users&#92;user&#92;file.txt"</code>. You must replace the
  * {@code '\'} characters with {@code "&#92;"} in the source code, otherwise
  * you will get "illegal unicode escape" errors. This also applies to
  * {@code <pre></pre>} blocks, {@code {@code ...}} blocks, etc. .</p>
  *
  * {@code <pre></pre>}, of course, isn't inline by default, but also formats
  * the code as monospaced:<pre>"C:&#92;Users&#92;user&#92;file.txt"</pre>
  * This can be adjusted with CSS, but there are easier solutions than this.
  *
  * <p>{@code <tt></tt>} is not allowed within Javadoc, it produces an error
  * like "tag not supported in the generated HTML version: tt".</p>
  *
  * <p>{@code {@code ...}} formats code as inline, but it doesn't interpret HTML
  * numeric character references, even though backslashes <em>must</em> be
  * escaped: {@code "C:&#92;Users&#92;user&#92;file.txt"}</p>
  *
  * <p>{@code {@literal ...}} also renders text inline and requires backslashes
  * to be escaped, but it also doesn't interpret character references:
  * {@literal "C:&#92;Users&#92;user&#92;file.txt"}</p>
  *
  * <p>The only CSS-free solution, then, is using a {@code <code></code>} block
  * and escaping the backslashes using character references. This is the
  * simplest solution to allow inline, monospaced Windows filesystem paths in
  * Javadoc. The following code:</p>
  *
  * <p>{@code<code>"C:&#92;Users&#92;user&#92;file.txt"</code>}</p>
  *
  * <p>...produces the following output:
  * <code>"C:&#92;Users&#92;user&#92;file.txt"</code></p>
  *
  * <hr style="height:1px;border:0;border-top:1px solid #CCC">
  *
  * <h2><strong>Edge Case 1: Wildcards in Paths</strong></h2>
  *
  * <p>It's easy to run into issues with Linux filesystem paths, too. If a path
  * has a glob {@code '*'} in it, followed by a forward slash (<code>"&#42;/"</code>),
  * this could be interpreted as the end of the Javadoc comment, which begins
  * with {@code "/**"}.</p>
  *
  * <p>But neither {@code {@code ...}} nor {@code {@literal ...}} interpret the
  * character reference {@code "&#42;"} as an asterisk ({@code "&#42;"} and
  * {@literal "&#42;"}). And {@code <tt></tt>} is again not allowed. So all we
  * have left are {@code <pre></pre>} and {@code <code></code>}.</p>
  *
  * <p>Fortunately, both of these properly interpret HTML character references
  * and both are monospaced. Here's the inline {@code <code></code>} version:
  * <code>"&#42;/"</code>. This is produced by the following code:</p>
  *
  * <p>{@code <code>"&#42;"</code>}</p>
  *
  * {@code <pre></pre>} can also be used, but it won't be inline by default:
  * <pre>"&#42;"</pre>
  *
  * <p>The above is produced by the following code:</p>
  *
  * <p>{@code <pre>"&#42;"</pre>}</p>
  *
  * <hr style="height:1px;border:0;border-top:1px solid #CCC">
  *
  * <h2><strong>Summary</strong></h2>
  *
  * <p>When including Windows or Linux filesystem paths in Javadoc, make sure to
  * escape all asterisks {@code '*'} and backslashes {@code '\'} with their HTML
  * character sequences ({@code "&#42;"} and {@code "&#92;"}, respectively). Also
  * note that these sequences will only be properly rendered / expanded if the
  * innermost tag pair is {@code <pre></pre>} or {@code <code></code>}. Any other
  * sequence ({@code {@code ...}}, {@code {@literal ...}}, etc.) will not render
  * these characters correctly.</p>
  *
  **/

public class JavadocPaths {
  public static void main (String[] args) {
    // do nothing
  }
}