dotnet/roslyn

XML Doc Comment incorrectly indents code CDATA section

开放

#27,150 创建于 2018年5月25日

 (6 条评论) (6 个反应) (0 位负责人)C# (4,257 个派生)batch import
Area-CompilersBughelp wanted

仓库指标

星标
 (20,414 个星标)
PR 合并指标
 (平均合并 6天 17小时) (30 天内合并 256 个 PR)

描述

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

贡献者指南