Raw String Literals for JavaDoc

[Brian Goetz]

Indeed this is out of scope for Amber, but it's a real issue.  I know 
there's been some discussion on making it easier to provide code samples 
in JavaDoc; I would ask over on

     http://mail.openjdk.java.net/mailman/listinfo/javadoc-dev

On 1/18/2019 11:05 AM, Nir Lisker wrote:
> 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/