Formatting documentation strings in hover popups.

The JSON language server supports markdown formatted docstrings, which enables us to write nice looking popups such as:

Can LemMinX do something like that as well?

It appears all <xs:documentation> contents is streamed as unformatted plain text with all kinds of whitespace and newlines etc. removed. So even plain text formatted docstring as the one from the following example result in poor user experience at the moment.

Result

Source

 <xs:annotation>
  <xs:documentation>
   See http://www.w3.org/XML/1998/namespace.html and
   http://www.w3.org/TR/REC-xml for information about this namespace.

    This schema document describes the XML namespace, in a form
    suitable for import by other schema documents.  

    Note that local names in this namespace are intended to be defined
    only by the World Wide Web Consortium or its subgroups.  The
    following names are currently defined in this namespace and should
    not be used with conflicting semantics by any Working Group,
    specification, or document instance:

    base (as an attribute name): denotes an attribute whose value
         provides a URI to be used as the base for interpreting any
         relative URIs in the scope of the element on which it
         appears; its value is inherited.  This name is reserved
         by virtue of its definition in the XML Base specification.

    lang (as an attribute name): denotes an attribute whose value
         is a language code for the natural language of the content of
         any element; its value is inherited.  This name is reserved
         by virtue of its definition in the XML specification.
  
    space (as an attribute name): denotes an attribute whose
         value is a keyword indicating what whitespace processing
         discipline is intended for the content of the element; its
         value is inherited.  This name is reserved by virtue of its
         definition in the XML specification.

    Father (in any context at all): denotes Jon Bosak, the chair of 
         the original XML Working Group.  This name is reserved by 
         the following decision of the W3C XML Plenary and 
         XML Coordination groups:

             In appreciation for his vision, leadership and dedication
             the W3C XML Plenary on this 10th day of February, 2000
             reserves for Jon Bosak in perpetuity the XML name
             xml:Father
  </xs:documentation>
 </xs:annotation>

What the client receives is:

:: --> LemMinX textDocument/hover(583): {'textDocument': {'uri': 'file:///C:/Apps/Sublime%20Text/Data/Packages/Markdown%20Extras/Snippets/Link.sublime-snippet'}, 'position': {'line': 2, 'character': 5}}
:: <<< LemMinX 583: {'contents': {'value': 'See http://www.w3.org/XML/1998/namespace.html and http://www.w3.org/TR/REC-xml for information about this namespace. This schema document describes the XML namespace, in a form suitable for import by other schema documents. Note that local names in this namespace are intended to be defined only by the World Wide Web Consortium or its subgroups. The following names are currently defined in this namespace and should not be used with conflicting semantics by any Working Group, specification, or document instance: base (as an attribute name): denotes an attribute whose value provides a URI to be used as the base for interpreting any relative URIs in the scope of the element on which it appears; its value is inherited. This name is reserved by virtue of its definition in the XML Base specification. lang (as an attribute name): denotes an attribute whose value is a language code for the natural language of the content of any element; its value is inherited. This name is reserved by virtue of its definition in the XML specification. space (as an attribute name): denotes an attribute whose value is a keyword indicating what whitespace processing discipline is intended for the content of the element; its value is inherited. This name is reserved by virtue of its definition in the XML specification. Father (in any context at all): denotes Jon Bosak, the chair of the original XML Working Group. This name is reserved by the following decision of the W3C XML Plenary and XML Coordination groups: In appreciation for his vision, leadership and dedication the W3C XML Plenary on this 10th day of February, 2000 reserves for Jon Bosak in perpetuity the XML name xml:Father\r\n\r\nSource: [sublime-snippet.xsd](file:/C:/Apps/Sublime%20Text/Data/Packages/LSP-lemminx/catalogs/sublime/sublime-snippet.xsd)', 'kind': 'markdown'}, 'range': {'start': {'line': 2, 'character': 3}, 'end': {'line': 2, 'character': 13}}}

Note: I injected the content into an XSD called sublime-snippet.xsd which I am working on in order to provide intelligence features to write Sublime Text / TextMate resources.

[deathaxe]

Hmm.

With a bit of luck and playing around I managed to create something like:

But the required XML code looks a bit uncommon. Some tokens need to be escaped even twice (e.g.: <).

<xs:documentation>
	```xml&lt;br&gt;&amp;lt;key&amp;gt;...&lt;/key&amp;gt;&lt;br&gt;```&lt;br&gt;

	&lt;p&gt;The Property List key with the main tmPreferences keys.&lt;/p&gt;
	&lt;p&gt;&lt;u&gt;Valid values are:&lt;/u&gt;&lt;/p&gt;
	&lt;ul&gt;
	&lt;li&gt;name&lt;/li&gt;
	&lt;li&gt;scope&lt;/li&gt;
	&lt;li&gt;settings&lt;/li&gt;
	&lt;li&gt;uuid&lt;/li&gt;
	&lt;/ul&gt;
</xs:documentation>

Things get a bit better by wrapping the content into CDATA.

<xs:documentation>
    <![CDATA[
    ```xml<br>&lt;key&gt;...&lt;/key&gt;<br>```

    <p>The Property List key with the main tmPreferences keys.</p>
    <p>Valid values are:</p>
    <ul>
    <li>name</li>
    <li>scope</li>
    <li>settings</li>
    <li>uuid</li>
    </ul>
    ]]>
</xs:documentation>

I haven’t found any other XSD file doing so, which makes me think it is not intended to be needed.

Haven’t investigated in detail what’s going on, but it seems

1. the xs:documentation content is parsed as normal XML
2. only the pure text part is interpreted as html and converted to markdown

In short. I am not familiar with XML standard with regards to handling such doc strings but it looks like there is one conversion step too much taking place.

What I’d expect to produce the desired result is:

<xs:documentation>
	```xml
	<key>...</key>
	```

	The Property List key with the main tmPreferences keys.

	Valid values are:

	- name
	- scope
	- settings
	- uuid
</xs:documentation>

or maybe tags which are to be sent as is escaped with entities.

<xs:documentation>
	```xml
	&lt;key>...&lt;/key>
	```

	The Property List key with the main tmPreferences keys.

	Valid values are:

	- name
	- scope
	- settings
	- uuid
</xs:documentation>

[Timmmm]

Any HTML tag placed into a Markdown file is to be rendered as is per specification.

Almost no Markdown renderers do that for obvious reasons, including VSCode.

This all seems to be a big mess and I didn’t follow all of the above conversation but I can confirm that the CDATA technique mentioned above works fine in VSCode and it’s not too ugly:

      <![CDATA[
      <pre>x++ += 4</pre>

      <p>The Property List key with the main tmPreferences keys.</p>
      <p>Valid values are:</p>
      <ul>
      <li>name</li>
      <li>scope</li>
      <li>settings</li>
      <li>uuid</li>
      </ul>
      Also you can just use
      <br><br>
      If you want separate paragraphs.
      ]]>