Summary

Add javadoc option to enable syntax highlighting for code fragments in generated documentation.

Problem

Syntax highlighting for code fragments is a standard feature in documentation for programming languages. While it is possible to add syntax highlighting using the existing --add-script and --add-stylesheet options, there should be a one-stop solution to configure syntax highlighting for Java with a single command line option.

Solution

Add a zero-argument option to enable syntax highlighting for code fragments in generated documentation. The option adds the highlight.js library to the generated output, configured to support Java and a number of other common languages and formats. The associated stylesheet is configured to work well with the default JavaDoc style sheet.

The feature is configured to recognize snippet tags as well as <pre><code> and <pre>{@code} tags, using language attributes to determine the language of code fragments if available, and otherwise falling back to auto-detection. These attributes can also be used to disable highlighting for individual code fragments, setting their value to "text" or another suitable format that is not supported by this feature.

Specification

The following option is added to the Javadoc Standard Doclet:

    --syntax-highlight
                  Enable syntax highlighting for code fragments in {@snippet} tags
                  and <pre><code> elements.

The following section is added to the javadoc man page:

 <span id="option-syntax-highlight">`--syntax-highlight`</span>
 :   Enables syntax highlighting for code fragments in `{@snippet}` tags and
     `<pre><code>` elements. For snippets, the `lang` attribute is used to 
     determine the language of code fragments, which defaults to "java" for 
     inline snippets and is derived from the file extension for external 
     snippets. In HTML `<pre><code>` tags, the `class` attribute can be used
     to specify the language of the contained code fragment as shown below: 

     ```
     <pre><code class="language-java">...</code></pre>
     ```

     If neither of these attributes is available automatic language detection is
     applied. To disable syntax highlighting for a code fragment set the language
     to "text" using one of the mechanisms described above. The languages and 
     formats supported by this option are Java, Properties, JSON, HTML and XML.