Need a new JINJA filter that can take HTML / Markdown - like strings (found in semconv notes) and Javadoc-friendly them.

[jsuereth]

We need a way to take notes fields and turn it into well-formed javadoc strings. Currently, the Java community is using a render_markdown template that, in my opinion, lacks a good set of docs on what it really does.

See existing template.

Context: migrating java semconv to weaver is failing

[lquerel]

To summarize, here is what I'm proposing to extend the existing filter comment_with_prefix. I'm thinking about adding the following optional parameters:

• syntax: markdown (default), html
• comment_format: see the formats section defined below
• trim: true (default), false
• remove_trailing_dots: true, false (default)
• remove_line_breaks_in_sentences: true, false (default)
• inline_code_style: a Jinja expression to specify the formatting of inline code
• block_code_style: a Jinja expression to specify the formatting of block code
• strong_words: an array of words to bold (empty by default)
• strong_word_style: a Jinja expression to specify the formatting of strong words (by default "{{strong_word}}")
• more formatting options to come.

To simplify things, we could introduce a new section in weaver.yaml which will define the meaning of a new named format.

comment_formats:
  javadoc:
    syntax: html
    inline_code_style: "{@code {{code}}}"
    block_code_style: "{@snippet: {{code}}"

It should also be possible to define the default comment format in weaver.yaml as follow:

default_comment_format: javadoc

With this approach, we could have something as simple as the following in the Jinja template:

{{ brief | comment_with_prefix(prefix="  *") }}

or even simpler if we add the concept of prefix in the config:

{{ brief | comment }}

This will avoid having repetitive parameters throughout the templates for managing comments for a specific programming language.

Note: by default, we could update the default weaver.yaml file embedded in the weaver binary to pre-define the comment configuration for the most common languages.