Some markdown-formatted remarks are ported into triple slash comments with invalid structure

Open
#68 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
42/100
Issue type
Bug
Clarity
Mostly clear
Activity status
Stale
Tech stack
csharp

Research direction

Compare the source MemoryManager`1.xml remarks with the resulting MemoryManager.cs triple-slash comments shown in the issue. Trace the documentation-porting path that handles the remarks and format elements, then verify that the generated remarks have valid structure without duplicated content.

Written by the indexing model from the issue text.

Description

port-to-tripleslash

As seen in MemoryManager<T> from System.Memory in dotnet/runtime, some <remarks> sections are getting produced with invalid structure, and duplicated content.

From `MemoryManager`1.xml`

  <Docs>
    <typeparam name="T">The type of items in the memory buffer managed by this memory manager.</typeparam>
    <summary>An abstract base class that is used to replace the implementation of <see cref="T:System.Memory`1" />.</summary>
    <remarks>
      <format type="text/markdown"><![CDATA[  

The `MemoryManager<T>` class is used to extend the knowledge of types that <xref:System.Memory%601> is able to represent. For example, you can derive from `MemoryManager<T>` to allow <xref:System.Memory%601> to be backed by a <xref:System.Runtime.InteropServices.SafeHandle>.

> [!NOTE]
> The `MemoryManager<T>` class is intended for advanced scenarios. Most developers do not need to use it.

       ]]></format>
    </remarks>
  </Docs>

Before porting the docs into triple slash comments, this was the content of MemoryManager.cs:

    /// <summary>
    /// Manager of <see cref="System.Memory{T}"/> that provides the implementation.
    /// </summary>
    public abstract class MemoryManager<T> : IMemoryOwner<T>, IPinnable

After porting, this is the result:

    /// <summary>An abstract base class that is used to replace the implementation of <see cref="System.Memory{T}" />.</summary>
    /// <typeparam name="T">The type of items in the memory buffer managed by this memory manager.</typeparam>
    /// <remarks>The `MemoryManager<T>` class is used to extend the knowledge of types that <see cref="System.Memory{T}" /> is able to represent. For example, you can derive from `MemoryManager<T>` to allow <see cref="System.Memory{T}" /> to be backed by a <see cref="System.Runtime.InteropServices.SafeHandle" />.
    /// <format type="text/markdown"><![CDATA[
    /// > [!NOTE]
    /// > The `MemoryManager<T>` class is intended for advanced scenarios. Most developers do not need to use it.
    /// ]]></format></remarks>
    public abstract class MemoryManager<T> : IMemoryOwner<T>, IPinnable

The <remarks> section has the content duplicated, once inside the <format> and once before it, which is an invalid structure.

Dominant language
C#
Stars
14
Forks
21
PR merge metrics
No merged PRs in 30d

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from dotnet/api-docs-sync

All issues in dotnet/api-docs-sync

Similar issues

More C# issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.