Raw String Literals for JavaDoc

[Nir Lisker]

Hi,

I realize this might be out of scope for Amber.

There are difficulties including multi-line code snippets in a JavaDoc
because of the combination of HTML characters interpretation (like < >
which are used for generic) and Java ones (like @ which is used for
annotations). This requires the developer to jump through quite a few hoop
of using <pre>, <code>, {@code} and {@literal}.

A code snippet might look like:

  * <pre>
  * <code>new BeanTranslator.Builder()
  *   .translate(
  *     new{@code Translator<String, Integer>}(String.class, Integer.class)
{
  *      {@literal @}Override
  *       public Integer translate(String instance) {
  *         return Integer.valueOf(instance);
  *       }})
  *   .build();
  * </code>
  * </pre>

to display:

new BeanTranslator.Builder()
  .translate(
    newTranslator<String, Integer>(String.class, Integer.class) {
      @Override
      public Integer translate(String instance) {
        return Integer.valueOf(instance);
      }})
  .build();

Some mix-and-match approaches can be found in [1] under "Code Markup
Features at a Glance".

Would it be possible to have raw string literals in the JavaDoc, such that
one can do:

* `new BeanTranslator.Builder()
*  .translate(
*    newTranslator<String, Integer>(String.class, Integer.class) {
*      @Override
*      public Integer translate(String instance) {
*        return Integer.valueOf(instance);
*      }})
*  .build();`

and be done with it?

Thanks,
Nir

[1] https://reflectoring.io/howto-format-code-snippets-in-javadoc/