GNOME Bugzilla – Bug 685597
C# <code> tag in an <example> tag does not render as expected.
Last modified: 2015-01-03 21:28:24 UTC
Created attachment 225918 [details] Code Snippet Showing XML Tag Usage Documenting some C# code with the <example> and <code> tags does not render the code nicely on the documentation page. However, when using <remarks> with the <code> tag, code appears to render nicely. I can continue to use the <remarks> tag as a solution, however, I wish to use the <example> tag to follow the MSDN notes (seen here http://msdn.microsoft.com/en-us/library/9w4cf933(v=vs.80).aspx). Attached includes a snippet of example code and the image showing the doyxgen HTML output.
Created attachment 225919 [details] Rendering of C# XML Tagged Code
This bug also appears if <code></code> is used stand alone without any <example> or <remarks> tags.
I tested out the using <code> with the <remarks> tag as well and found something interesting. If I do this: <remarks> <code> //codeblock 1; </code> </remarks> <code> //codeblock 2; </code> both code blocks render correctly. It looks like the remarks tag somehow activates the correct code parser for C#
It seems that even an empty remarks section activates correct C# parsing. The following renders as expected: /// <remarks><!-- for doxygen --></remarks> /// <example> /// <code> /// ; /// ; /// </code> /// </example> The example tag isn't necessary, but it's typical usage. (Tested using v1.8.8)
[1] indicates that both the summary tag and remarks tag should activate XML-comment parsing. The following also renders as expected: /// <summary> /// Test /// </summary> /// <summary><!-- for doxygen --></summary> /// <example> /// <code> /// ; /// ; /// </code> /// </example> So it seems to be that the first summary tag isn't doing the trick. :( [1] https://github.com/doxygen/doxygen/blob/808b6174027ae53083aab386a7bc0eecc72c7a0d/src/docparser.cpp#L5966
The problem is that the <code>..</code> construct is overloaded in doxygen. It is both valid HTML markup that doxygen supports and also valid XML markup, so I made some detection mechanism to switch the parsing into 'XML' mode. I'll mark all 'primary' tags as listed here: http://msdn.microsoft.com/en-us/magazine/cc302121.aspx as triggers for the 'XML' mode. Should be fixed in the next GIT update.
This bug was previously marked ASSIGNED, which means it should be fixed in doxygen version 1.8.9. Please verify if this is indeed the case. Reopen the bug if you think it is not fixed and please include any additional information that you think can be relevant (preferrably in the form of a self-contained example).
Created attachment 293675 [details] Rendering of C# XML Tagged Code with Doxygen v1.8.9 Verified working in Doxygen v1.8.9. The provided attachment shows the original snippet of code rendering as expected. Thanks.