Created
December 17, 2018 15:12
-
-
Save awwsmm/699a186731382e7fe44a6f2caed45866 to your computer and use it in GitHub Desktop.
Filesystem paths (Windows and Linux) in Javadoc
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
/** | |
* 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:\Users\user\file.txt"</code>. You must replace the | |
* {@code '\'} characters with {@code "\"} 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:\Users\user\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:\Users\user\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:\Users\user\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:\Users\user\file.txt"</code>}</p> | |
* | |
* <p>...produces the following output: | |
* <code>"C:\Users\user\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>"*/"</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 "*"} as an asterisk ({@code "*"} and | |
* {@literal "*"}). 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>"*/"</code>. This is produced by the following code:</p> | |
* | |
* <p>{@code <code>"*"</code>}</p> | |
* | |
* {@code <pre></pre>} can also be used, but it won't be inline by default: | |
* <pre>"*"</pre> | |
* | |
* <p>The above is produced by the following code:</p> | |
* | |
* <p>{@code <pre>"*"</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 "*"} and {@code "\"}, 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 | |
} | |
} |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment