Raw String Literals for JavaDoc
Brian Goetz
brian.goetz at oracle.com
Fri Jan 18 16:21:14 UTC 2019
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/
More information about the amber-dev
mailing list