Il "Ottiene o imposta .." è necessario nella documentazione XML delle proprietà?

Sto cercando una raccomandazione di una best practice per i commenti XML in C #. Quando si crea una proprietà, sembra che la documentazione XML prevista abbia la forma seguente:

/// <summary>
/// Gets or sets the ID the uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID {
    get;
    set;
}

Ma poiché la firma della proprietà ti dice già quali operazioni sono disponibili per i client esterni della classe (in questo caso è entrambe le cose gete set) sento che i commenti sono troppo chiacchieroni e che forse sarebbe sufficiente quanto segue:

/// <summary>
/// ID that uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID {
    get;
    set;
}

Microsoft utilizza il primo modulo, quindi sembra che sia una convenzione implicita. Ma penso che il secondo sia migliore per i motivi che ho affermato.

Capisco che questa domanda è un adepto per essere contrassegnato come non costruttivo, ma la quantità di proprietà che si devono commentare è enorme e quindi credo che questa domanda abbia il diritto di essere qui.

Apprezzerò qualsiasi idea o collegamento alle pratiche ufficiali raccomandate.

La firma può indicare ad altre parti di codice quali operazioni sono disponibili; tuttavia, non sono chiaramente mostrati al programmatore mentre sta lavorando e la documentazione XML è destinata alle persone a consumare e non a un compilatore.

Prendi questa classe per esempio:

public class MyClass
{
    /// <summary>
    /// The first one
    /// </summary>
    public int GetOrSet { get; set; }

    /// <summary>
    /// The second one
    /// </summary>
    public int GetOnly { get; private set; }

    /// <summary>
    /// The last one
    /// </summary>
    public int SetOnly { set; private get; }
}

Quando l'intellisense viene tirato su per accedere a una di queste proprietà non vi è alcuna indicazione su quali possano essere scritte, da cui leggere o entrambe:

Allo stesso modo, quando si visualizza la documentazione, non siamo abbastanza sicuri:

Pertanto, aggiungiamo i get o i set , i get o i set per semplificare il programmatore durante la scrittura del codice. Non sarebbe certo scrivere un grosso blocco di codice che legge ed elabora alcuni dati solo per scoprire che non è possibile riscrivere tali dati nella proprietà come previsto.

StyleCop utilizza la Gets or Sets ...notazione che applica con la regola SA1623 .

La pagina collegata elenca un altro caso che non hai elencato:

/// <summary>
/// Gets a value indicating whether the item is enabled.
/// </summary>
public bool Enabled
{
    get { return this.enabled; }
}

L'altra opzione che elenchi sarebbe.

/// <summary>
/// ID that uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID { get; set; }

vs

/// <summary>
/// ID that uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID { get; }

Che non avrebbe fornito informazioni sul suggerimento Intellisense che la proprietà è di sola lettura, si potrebbe trovare una convenzione per questo caso, ma Gets ..., Gets or Sets...fa il lavoro bene imo.

Ci sono anche altri vari elencati nella regola StyleCop che sono chiari usando il Gets or Sets...ma potrebbero non esserlo.

Inoltre, quando si genera la documentazione da qualcosa come Doxygen o Sandcastle, la notazione completa documenterebbe meglio l'API (ad esempio).

L'unica volta in cui aggiungo informazioni sull'ottenimento e l'impostazione di una proprietà nei commenti XML è quando non si comporta come previsto (ottenere e impostare direttamente dal pubblico).

Se uno è privato o contiene una logica aggiuntiva, li menziono, altrimenti documento solo l'intento della proprietà.

Sarei più felice con la versione più dettagliata.

L'altro è come avere un commento di "increment counter" dopo, beh, incrementare una variabile counter.

È ovvio che c'è un Get and Set. Se avessi un setter privato, sarebbe ovvio come avresti la parola chiave privata.

I commenti dovrebbero aggiungere valore, non solo essere la versione dei commenti di ciò che il codice è in realtà.