Roslyn: XML Doc Comment incorrectly indents code CDATA section

[joelmartinez]

Version Used:
dotnet --version reports: 2.1.200

Steps to Reproduce:

1. dotnet new library to create a new library project
2. Add a DocumentationFile element to the csproj's PropertyGroup element:

<DocumentationFile>bin\$(Configuration)\$(TargetFramework)\$(AssemblyName).xml</DocumentationFile>

1. Add a code example to the triple slash, where the code tag contains a CDATA section

using System;

namespace csdoccomment
{
    /// <summary>This is the Summary</summary>
    /// <example>
    /// <code language="c#">
    /// <![CDATA[
    /// // No Indent
    ///     // four spaces
    ///         /// eight spaces
    /// ]]>
    /// </code>
    /// </example>
    public class Class1
    {
    }
}

1. Compile with dotnet build

Expected Behavior:
I would expect the CDATA section to retain the expected level of indention as when authored, relative to the triple slash delimiter ... so the XML file should look as such

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>csdoccomment</name>
    </assembly>
    <members>
        <member name="T:csdoccomment.Class1">
            <summary>This is the Summary</summary>
            <example>
            <code language="c#">
            <![CDATA[
// No Indent
    // four spaces
        /// eight spaces
]]>
            </code>
            </example>
        </member>
    </members>
</doc>

Actual Behavior:
However, as you can see, the contents of the CDATA element are indented relative to the indent level of the parent XML tag.

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>csdoccomment</name>
    </assembly>
    <members>
        <member name="T:csdoccomment.Class1">
            <summary>This is the Summary</summary>
            <example>
            <code language="c#">
            <![CDATA[
            // No Indent
                // four spaces
                    /// eight spaces
            ]]>
            </code>
            </example>
        </member>
    </members>
</doc>

The contents of the CDATA section are meant to respect the whitespace ... and in many cases, whitespace can be significant, especially when we're talking about code examples for languages like python or F#.

/cc @dend, @terrajobst

[lobrien]

Hmm... Not sure what to think about the start of line token: is it triple-slash plus a single space, or is it the straight triple-slash?

That is, would /// //X be //X or _//X (I've made the leading space a _ to make it more visible)? The latter (triple-slash alone indicates the start of a comment line) seems "more correct" from an XML and parsing standpoint, although I admit /////X is clearly going to be error-prone for both writers and readers.

[joelmartinez]

@lobrien I'd love to hear from someone with more insight/experience in this codebase ... but it looks like the parser accounts for a large number of variations in how users enter that information; as you can see in the unit tests

_If I had to guess_, it probably takes the "minimum indent", and uses that as the base. So in the example above, everything is indented from the /// by one space, and so it offsets every line by that one space.

[joelmartinez]

From what I gather (the internal API's design is rather circuitous) ... the XML documentation file is generated through this class
https://github.com/dotnet/roslyn/blob/fab7134296816fc80019c60b0f5bef7400cf23ea/src/Compilers/CSharp/Portable/Compiler/DocumentationCommentCompiler.DocumentationCommentWalker.cs

@gafter ... if I were to create a PR to fix this issue, should I do anything before I get to the implementation stage? should I be submitting some sort of language request for review, as suggested here? Or should anyone sign off on it before a PR would be accepted?

[gafter]

@joelmartinez I think you can go ahead and propose a fix. I don't think there are any design issues to be debated.