è la documentazione XML utilizzata per documentare solo l'API esterna?

Question

è la documentazione XML utilizzata per documentare solo l'API esterna?

#1 da (5 voti)
#2 da (1 voti)

3

Sto usando i commenti della documentazione XML per documentare un nuovo progetto. Tutti i miei metodi API pubblici sono documentati utilizzando le tre barre richieste per la documentazione XML.

I miei metodi interni (protetti e privati) sono documentati usando doppie barre ( // ) e barra stella ( /* */ ). Questo perché non credo che questi commenti debbano apparire nella documentazione dell'API pubblica. Ad esempio, ho sviluppato un gruppo di classi che utilizzano il modello Chain of Responsibility ( link ), tuttavia non credo che gli utenti di queste classi debbano sapere che il pattern Chain of Responsibility è usato internamente - solo altri sviluppatori di queste classi devono saperlo.

L'ho capito correttamente, cioè la documentazione XML utilizzata per documentare solo l'API esterna? Devo anche dire che queste classi usano il modello Chain of Responsibility (o qualsiasi pattern che io uso).

Il motivo per cui lo chiedo è perché altri sviluppatori guarderanno presto questo codice e sto cercando di promuovere il principio del minimo stupore.

c# documentation-generation

posta w0051977 05.01.2018 - 17:09

fonte

2 risposte

Leggi altre domande sui tag c# documentation-generation

Memorizza i dati csv come righe o colonne in vista dell'elaborazione necessaria? Risposta significativa all'utente dopo che il suo CSV caricato è stato elaborato?

score 5 · Answer 1

I do not believe these comments should appear in the public API documentation

Per privato, è corretto. Per i metodi di protected di classi non sigillate, la documentazione dell'API pubblica deve contenere sicuramente una descrizione, in quanto possono essere richiamati in una classe derivata da un utente della tua libreria.

Have I understood this correctly i.e. is XML Documentation used to document the external API only.

Tuttavia, IMHO non è una buona idea. Se non si desidera che la documentazione XML dei metodi privati appaia nei documenti dell'API pubblica, è meglio trovare un modo per configurare lo strumento di generazione della documentazione per non inserire tali commenti Xml privati nel documento generato. Se stai utilizzando Sandcastle per generare i tuoi documenti, questo sembra essere l'impostazione predefinita .

I commenti XML per tutti i metodi, inclusi i metodi privati, sono utili per te stesso o per il tuo team (il manutentore della libreria), perché viene visualizzato dalla funzione intellisense di Visual Studio quando si utilizza tale metodo. Inoltre, diventerà piuttosto ingombrante e soggetto a errori di utilizzare una sintassi di commento diversa per i metodi privati rispetto a qualsiasi altra cosa, o di modificare la sintassi dei commenti ogni volta che si rende un metodo pubblico privato o viceversa.

score 1 · Answer 2

Dipende, questa documentazione verrà fornita ai clienti esterni o è per riferimento interno? Se lo stai fornendo a sviluppatori esterni, solo pubblici e amp; i commenti protetti dovrebbero essere generati nei documenti. Se lo stai utilizzando per scopi interni, sentiti libero di generare documenti per tutto ciò che ha un commento di un doc. Avevo un progetto in cui volevamo entrambi, quindi ho creato due diversi progetti SandCastle, uno per il cliente e uno che è stato pubblicato sulla nostra intranet interna.

In ogni caso, non è una questione di cosa dovrebbe avere un commento, è una questione di quali commenti sono inclusi nella generazione del tuo documento.

Per impostazione predefinita, SandCastle non esporta i commenti dei documenti per i metodi privati , così puoi andare avanti e aggiungere commenti al doc per i metodi privati, se lo desideri. Non saranno esportati nei documenti generati a meno che tu non dica esplicitamente a SandCastle di farlo.