6 Replies Latest reply: Dec 4, 2008 9:33 AM by 843810 RSS

    XML example file in a comment

    843810
      Hi,

      i need to know how to put a little XML example file in a comment. This is what i have :

      * to be consulted. Next you can see an example of a configuration file :

      /**
      *<P>
      * blablablablalbablablabla
      *</p>
      * <br>
      *
      *
      * <?xml version="1.0" encoding="utf-8" ?><br>
      * <!-- Comments --><br>
      * <CONF><br>
      * <FONT><br>
      * <FONT_SIZE>11</FONT_SIZE><br>
      * <FONT_TYPE>SansSerif</FONT_TYPE><br>
      * </FONT><br>
      * <THREADPOOL><br>
      * <MAX_POOL_SIZE>30</MAX_POOL_SIZE><br>
      * </THREADPOOL><br>
      * <FIELDS><br>
      * <FIELD_NAME>to</FIELD_NAME><br>
      * <FIELD_NAME>subject</FIELD_NAME><br>
      * </FIELDS><br>
      * <WAIT_TIME>0.1</WAIT_TIME><br>
      * </CONF><br><br>
      *
      *
      */

      I tried using the <code> tag but it does not work. anyone??

      thanks in advance
        • 1. Re: XML example file in a comment
          843810
          Do you want the XML to appear with angle bracket, like <CONF> in the
          resulting HTML page? If so, simply use the entities < and >
          as follows, and you can either enclose the whole thing in <code>
          with <br> at the end of each line, or just enclose the whole thing
          in <pre>. It's ugly, but it should work.

          /**
          *<P>
          * blablablablalbablablabla
          *</p>
          * <br>
          *
          * <pre>
          * &lt;?xml version="1.0" encoding="utf-8" ?&gt;
          * &lt;!-- Comments --&gt;
          * &lt;CONF&gt;
          * &lt;FONT&gt;
          * ...
          * </pre>
          */

          etc.

          -Doug Kramer
          javadoc team
          • 2. Re: XML example file in a comment
            843810
            I have a similar problem, with a larger XML structure. However, I want the developers to maintain the XML within the comments and, as you may expect, by encoding the characters it looks ugly and they are less likely to update it. Is there a way to just include a block of XML as text within the JavaDoc (similar to using the CDATA tag in XML?)
            • 3. Re: XML example file in a comment
              843810
              It's okay, I found that it seems to work if I put a space in front of the first angle bracket:

              < start XML>
              < element />
              < / start XML>

              It seems to work
              • 4. Re: XML example file in a comment
                843810
                <pre>
                {@code
                <example>
                <message>no special escaping nonsense</message>
                <hopethishelps>true</hopethishelps>
                </example>
                }
                <pre>
                • 5. Re: XML example file in a comment
                  thomas.behr
                  TrogDog wrote:
                  <pre>
                  {@code
                  <example>
                  <message>no special escaping nonsense</message>
                  <hopethishelps>true</hopethishelps>
                  </example>
                  }
                  <pre>
                  You do realize that you resurrected a thread that is over five years old, right? Moreover, {@code} was introduced in Java 1.5 and as such was not available in 04/2003.
                  • 6. Re: XML example file in a comment
                    843810
                    TrogDog, thanks for resurrecting this post; it seems all questions about this topic are answered with the idiodic suggestion of substituting character entities for the < and > signs, a rather crude and inefficient way to document code.

                    In my case, the <pre> tag did not render at all, however, this minor adjustment worked like a charm:

                    <xmp>
                    <example>
                    <message>no special escaping nonsense</message>
                    <hopethishelps>true</hopethishelps>
                    </example>
                    <xmp>

                    Node the change from <pre> to <xmp>, and the removal of {@code}. If you leave {@code} then the < and > will be displayed as character entities, the absolute opposite of the intended effect.


                    Thank you for the elegant solution!