Format comments messes up CDATA element in xml documentation comments

[Crono1981]

Environment

• Visual Studio version: 2017
• CodeMaid version: 10.5
• Code language: C#

Description

Suppose you have the following xml documentation comments on a method:

/// <example>
/// The following implements the <see cref="IComparable{T}"/> interface and uses the builder to construct a list of comparison handlers. Then, it invokes the <see cref="Compare"/> method and returns the result.
/// <code>
/// <![CDATA[
/// class Foo : IComparable<Foo>
/// {
///
///     int fieldA = 0;
///     string fieldB = "value";
///
///     public int CompareTo(Foo other)
///     {
///         var builder = new ComparisonBuilder();
///
///         return builder.Add(
///             () => fieldA.CompareTo(other.fieldA),
///             () => fieldB.CompareTo(other.fieldB)
///         ).Compare();
///     }
/// }]]>
/// </code>
/// </example>

Upon running CodeMaid with the format comments option on, it will rewrite the doc like this:

/// <example>
/// The following implements the <see cref="IComparable{T}"/> interface and uses the builder
/// to construct a list of comparison handlers. Then, it invokes the <see cref="Compare"/>
/// method and returns the result.
/// <code>
/// <![CDATA[
/// class Foo : IComparable<Foo>
/// {
///
/// int fieldA = 0;
/// string fieldB = "value";
///
/// public int CompareTo(Foo other)
/// {
/// var builder = new ComparisonBuilder();
///
/// return builder.Add(
/// () => fieldA.CompareTo(other.fieldA),
/// () => fieldB.CompareTo(other.fieldB)
/// ).Compare();
/// }
/// }]]>
/// </code>
/// </example>

As you can see, indentation has been removed and the whole thing just looks ugly.

I think that whatever is found within a CDATA element should remain untouched, regardless of the format comments setting.

[codecadwallader]

Thanks for reporting the issue. @willemduncan when you have a chance can you respond? I didn't see CDATA anywhere in the docs https://docs.microsoft.com/en-us/dotnet/csharp/codedoc so perhaps its best to find a different way to flag those comments (e.g. by their <code> element or I know the easiest one is to remove the leading space).

[fschricker]

Is there a way I could possibly help? Test something?

[codecadwallader]

Thanks for offering to help. @willemduncan anything you could advise?

[w5l]

CData does not automatically mean we should interpret literally, it is just an XML hint.

In an XML document or external parsed entity, a CDATA section is a section of element content that is marked for the parser to interpret purely as textual data, not as markup. (from Wikipedia)

The <code> block however, should be interpreted literally instead of parsed. I think the combination of the two might cause an issue here. Try removing the <![CDATA[ .... ]]> and see what happens? What's the reason for including that anyway?

[Crono1981]

@willemduncan in my example, removing CDATA will result in badly formed XML for the comment, because of this line:

/// class Foo : IComparable<Foo>

It will complain about an unclosed Foo element.

Of course I could encode the line this way:

/// class Foo : IComparable$lt;Foo>

I however find that to be quite a pain in the a** to have to do so. Especially if you plan on having lots of examples in your doc.

[Crono1981]

Likewise, any code making use of greater than / lower than operators will also have this issue.

[Crono1981]

I've found this MSDN blog post from 2006 (!) that mentions using CDATA to encapsulate example code segments:

https://blogs.msdn.microsoft.com/ansonh/2006/09/11/c-xml-documentation-comments-faq/

[w5l]

Whoah that is some arcane C# 1.0 documentation you dug up there 👍 The issue with gt/lt getting encoded is known, see #561. I'll add 'CDATA' support to the requirements list.

I've tried some approaches for getting both these issues fixed, but it's harder than expected. The formatting code uses XElement to parse the text, which automatically encodes the XML special chars when writing output. There is a WriteRaw method which can fix this, but then I got into issues with your CDATA blocks. It's decending so deep into XML handling that it might be better just to drop native XML parsing altogether... but I'm open for suggestions.

[Crono1981]

Just so we're clear: I don't expect CodeMaid tidying up my code example as it does with regular code. :)

I just feel that CDATA objects found within code comments should be ignored and remain untouched. Even if they do happen to have long lines or stuff like that. For all I care, CodeMaid may replace a CDATA block with an empty string, do its comment tidying up routine and then just put back the unaltered CDATA blocks at the expected positions.

I don't know how other users might feel about this but I would find it quite okay that CodeMaid can't "fix" CDATA blocks. Seems totally fair.

[w5l]

At the moment your CDATA block is inside a <code> block and will not (OK, should not) be touched at all. It's definitely not parsed as code ;) The problem is with the XML reader/writer used to format the comment that the code is part of. It treats CDATA different, and causes the current problems with whitespace disappearing.

[ipointer-certifid]

I can second this issue, but for ANY HTML tag in your comments. It is useful to be able to use a <see cref="...">, etc. in the summary comments.

The good news is, it doesn't seem to affect how it renders in the tools.

[w5l]

That is just a line break in the XML tag, works as intended. Look for the setting "Keep XML tags together" to control this behavior.

[ipointer-certifid]

That is just a line break in the XML tag, works as intended. Look for the setting "Keep XML tags together" to control this behavior.

Thank you!

Cheers!

[ericmschmidt]

Any update to this? I'm also experiencing issues with CodeMaid reformatting some comments that are contained within CDATA. I've got two different classes where I use this and in one it will reformat incorrectly while in the other it leaves the comment alone as is. I've tried looking and I don't see any difference between the files.