cref values including generic types on method parameters get formatted incorrectly
Nobody has claimed this yet.
Assessment
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Newbie friendliness
- 45/100
- Issue type
- Bug
- Clarity
- Mostly clear
- Activity status
- Stale
- Tech stack
- csharp
- Domain
- documentation
Research direction
Start by reproducing the conversion using the ArrayPool`1.xml example and trace how the API docs sync tool formats cref values for generic method parameters. Done means the generated triple-slash comment uses a valid cref such as ArrayPool{T}.Return(T[], bool) instead of placeholders like {T} in the parameter type.
Written by the indexing model from the issue text.
Description
While porting from API docs into triple slash comments, a scenario was encountered with <see cref="" /> elements that reference methods accepting generic arguments where the resulting triple slash comments are incorrectly formatted.
Example from ArrayPool`1.xml:
<param name="clearArray">Indicates whether the contents of the buffer should be cleared before reuse.
If <paramref name="clearArray" /> is set to <see langword="true" />, and if the pool will store the buffer
to enable subsequent reuse, the <see cref="M:System.Buffers.ArrayPool`1.Return(`0[],System.Boolean)" />
method will clear the <paramref name="array" /> of its contents so that a subsequent caller using the
<see cref="M:System.Buffers.ArrayPool`1.Rent(System.Int32)" /> method will not see the content of the
previous caller. If <paramref name="clearArray" /> is set to <see langword="false" /> or if the pool will
release the buffer, the array's contents are left unchanged.</param>
This results in:
/// <param name="clearArray">Indicates whether the contents of the buffer should be cleared before reuse.
If <paramref name="clearArray" /> is set to <see langword="true" />, and if the pool will store the buffer
to enable subsequent reuse, the <see cref="System.Buffers.ArrayPool{T}.Return({T}[],bool)" />
method will clear the <paramref name="array" /> of its contents so that a subsequent caller using the
<see cref="System.Buffers.ArrayPool{T}.Rent(int)" /> method will not see the content of the
previous caller. If <paramref name="clearArray" /> is set to <see langword="false" /> or if the pool will
release the buffer, the array's contents are left unchanged.</param>
The <see cref="System.Buffers.ArrayPool{T}.Return({T}[],bool)" /> is invalid. It should be <see cref="System.Buffers.ArrayPool{T}.Return(T[], bool)" />.
- 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
-
type/automation type/tech-debt
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
-
t/bug
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
-
ci-failure-cause test-failure
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
-
area:auth FE mvp P3
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
klasolsson81/jobbliggaren#1788 ·