search

dotnet / api-docs-sync

Tools for porting documentation from intellisense xmls to api-docs, or from api-docs to triple slash comments.
MIT License
10 stars 16 forks source link

cref values including generic types on method parameters get formatted incorrectly #67

Open jeffhandley opened 3 years ago

jeffhandley commented 3 years ago

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)" />.

jeffhandley commented 3 years ago

My gut tells me this is going to be a bit tricky to resolve. I don't have a fix going for it, and I currently plan to work around it by just correcting the resulting code after the port.