Some markdown-formatted remarks are ported into triple slash comments with invalid structure
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
- Domain
- documentation, tooling
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
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
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from dotnet/api-docs-sync
-
Difficulty 3/5 1-2 days Newbie friendliness 42/100
dotnet/api-docs-sync#182 ·
-
Difficulty 3/5 1-2 days Newbie friendliness 45/100
dotnet/api-docs-sync#181 ·
-
Difficulty 4/5 3-5 days Newbie friendliness 35/100
dotnet/api-docs-sync#180 · 1 comment ·
-
Difficulty 4/5 3-5 days Newbie friendliness 35/100
dotnet/api-docs-sync#179 ·
-
Difficulty 3/5 1-2 days Newbie friendliness 35/100
dotnet/api-docs-sync#178 · 1 comment ·
All issues in dotnet/api-docs-sync
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
nightscout/nocturne#1379 ·
-
priority-0
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
-
Difficulty 1/5 Under an hour Newbie friendliness 78/100
StackExchange/StackExchange.Redis#3249 ·
-
[Feat] 조합 영역 구분선 개선 Open
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
-
documentation
Difficulty 2/5 1-3 hours Newbie friendliness 72/100