cref values including generic types on method parameters get formatted incorrectly

Aperta
#67 1 commento 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
3/5
Tempo stimato
1-2 giorni
Idoneità per principianti
45/100
Tipo di issue
Bug
Chiarezza
Abbastanza chiara
Stato di attività
Ferma
Stack tecnologico
csharp
Ambito
documentation

Direzione di ricerca

Inizia riproducendo la conversione usando l'esempio ArrayPool`1.xml e traccia il modo in cui lo strumento di sincronizzazione della documentazione API formatta i valori cref per i parametri dei metodi generici. Il lavoro è completato quando il commento generato a tre slash usa un cref valido come ArrayPool{T}.Return(T[], bool) invece di segnaposto come {T} nel tipo del parametro.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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

Lingua principale
C#
Stelle
14
Fork
21
Metriche di merge delle PR
Nessuna PR unita negli ultimi 30g

Guida per i contributori

Nessuna guida per i contributori indicizzata per questo repository

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di dotnet/api-docs-sync

Tutte le issue di dotnet/api-docs-sync

Issue simili

Altre issue su C#

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.