7

The Problem:

I have a xsd schema with included documentation, like:

<xs:element name="Tag" type="XTag">
  <xs:annotation>
    <xs:documentation>
      Do like this:
       - foo
       - bar
    </xs:documentation>
  </xs:annotation>
</xs:element>

When I view the documentation in Eclipse, the white-spaces are truncated to a single space, so I end up with:

Do like this: - foo - bar

This naturally limits readability when documentation is more than a little note. In javadoc for instance, one can one html tags to format the documentation

The question:

Is there any way to format the documentation, at least just adding newlines?

Some details:

I'm doing everything in Eclipse. The XSD i write is added to preferences -> XML -> XML catalog, so I can get content assist and view documentation in the XML editor.

It's an internal tool and the only foreseeable place the documentation will be viewed is through Eclipse in the way described above. So if it works in eclipse, it's good enough :)

Tobber
  • 7,211
  • 8
  • 33
  • 56

2 Answers2

6

Embed your documentation into <![CDATA[ ]]> and use html expressions. Sample below should be rendered correctly.

<xs:annotation>
    <xs:documentation>
    <![CDATA[
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.<br/>
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. 
<p><b>Duis aute</b> irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. </p>
<br/>
<b>Excepteur sint occaecat cupidatat non proident,<br/>
<ul>
    <li>sunt in culpa qui officia</li> 
    <li>deserunt mollit anim</li>
    <li>id est laborum.</li>
</ul>
    ]]>
    </xs:documentation>
</xs:annotation>

Tested with Spring Tool Suite v3.6.4 (Eclipse 4.4.2)

vahapt
  • 1,685
  • 1
  • 21
  • 26
  • 1
    This sounds like a great solution, but I am not able to confirm it myself anymore. If somebody else can confirm that this is working I will accept this as the correct answer. – Tobber Dec 30 '15 at 10:45
  • I'm using DocFlex/XML for generating my XSD documentation and therefore this is not working. – Mario Murrent Apr 06 '16 at 14:18
3

Try using html like <br/> for newline and List<ul><li>item</li></ul> for list items.

Not sure if you should be embedding "under construction" animated gifs or even tables though. It worked for me while documenting an xsd and creating a corresponding xml using oXygen XML editor.

jos
  • 823
  • 6
  • 8
  • It works for some tags, e.g., `
    ` and `` but not for `
      ` which shows up unchanged in the Eclipse tooltip. An important note is, that one has to escape the brackets, so `
      ` becomes `<br/>`. If you don't do it Eclipse will skip the tag and it's content.
     – Tobber Jan 16 '13 at 09:52