cref values including generic types on method parameters get formatted incorrectly

Open
#67 1 comment 0 reactions 0 assignees View on GitHub

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

port-to-tripleslash

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

  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.