ArtsiomCh / JDCleanRead

Plugin for IntelliJ platform IDEs. Making JavaDoc comments more readable

JavaDoc Clean Read plugin for IntelliJ platform IDEs.

Why?

HTML and JavaDoc tags, as well as HTML escaped chars make the text of JavaDoc comments hard to read (sometimes almost impossible) in the Code Editor.
We can open the quick documentation window (Ctrl+Q or ⌃J or View > Quick Documentation from the menu). But that need additional actions and give the text formatted withing different style then source code. Also links at the JavaDoc comment lead to the source code of linked element, but at the quick documentation window it leads to generated JavaDoc of linked element, which is not what we usually desire.

How?

Hiding(folding) HTML tags;

Unescape HTML escaped chars;

Text styles for value of tags: <code> | <tt> | <li> | <b> | <i> | <a href/name=...> | @code | @literal | @link | @linkplain | @value;

Tag and tag's value text styles are customisable at Settings -> Editor -> Color Scheme -> JavaDoc Clean Read.

Both HTML-JavaDoc tags hiding and HTML escaped chars unescaping are implemented through IntelliJ code folding. So all shortcuts (Ctrl+. Ctrl+NumPad + and others) works. As well as code folding toggles (like ⌂) shown in the editor to the left of the corresponding multiline folding regions.

There are some limitations for corner cases in current release: multiline tags (fixed at 0.3.0), nested tags (fixed at 0.3.0), ... But mostly it works fine.

Side by side comparison of java.nio.charset.Charset and java.lang.String top JavaDoc comment:

For even more fun see java.util.regex.Pattern ;)

Alternatives?

I don't know any... :(
Would be glad if JetBrain implements that more proper way as part of IntelliJ platform.

License

Plugin is open-source software and is licenced under GPL v3 licence.

Versions

0.3.1 - Make new functionality (see 0.3.0) available since 181.0 instead of 183.0

0.3.0 - Multi-line Html/Javadoc tag and tag's value support added (all possible cases founded). Also added/fixed:
  - Annotate Html/Javadoc tag and Html Escaped chars (with Bordering effect by default - customisable).
  - Customisation for <b> and <i> tags added.
  - Proper support for both Default and Darcula themes added.
  - fix IDEA-198738.
  - <a name=...> support (and separation from <a href=...>) added.
  - CPU usage and Mem allocation optimisations.

0.2.2 - Highlight <a href=...> tag value </a> (customisable).

0.2.1 - Few improvements:
  - @literal tag support added;
  - text inside @code and @literal is not interpreting as HTML markup;

0.2.0 - Refactoring and covering by tests. Plugin should be more stable and less error prone. Also fixed issues with:
  - Multiline @link and @code tag folding;
  - @linkplain tag added (@link rules applied);
  - Unescaping for not valid escaped chars sequence;
  - Not interpreting the text as HTML markup inside @code tag (<Generics>);

0.1.0 - Initial release:
  * hiding(folding) HTML tags;
  * unescape HTML escaped chars;
  * text styles for tags: <code> | <tt> | <b> | <i> | @code | @link (fix IDEA-197760).