Come devo documentare la mia codice C #? [chiuso]

Question

sto costruendo la documentazione per il nostro C # API contenente:

1. Una panoramica generale e la descrizione dello stato attuale come un file doc / pdf.
2. Un'API libreria di classi in un file CHM utilizzando Sandcastle.

Domande:

1. Dovrei unire questi due nello stesso file chm? Che cosa è un buon modo per unirli?
2. Ho bisogno di escludere alcune classi / pacchetti. Come faccio a specificare che nel SandCastle?
3. Esso genera la documentazione per il codice VB e il codice Visual C ++. Come posso cambiare questo? O dovrei lasciarlo, sapendo che sono solo utilizzando il codice di sicurezza?
4. Dove posso trovare HTML Help 2.x Visualizzatore Percorso sul mio sistema?

Modifica:

I commenti che faccio sopra metodi, campi e le classi non vengono generati nella documentazione.

Che cosa devo fare?

Answer 1

Vi consiglio di utilizzare Sandcastle Aiuto File Builder da Codeplex. Si può facilmente includere ed escludere gli spazi dei nomi, ma non sono sicuro di come fare per escludere una singola classe. È possibile impostare l'opzione per generare unica documentazione per le classi pubbliche / protette, ma non so se questo si adatta al contesto.

È anche possibile destinare una lingua specifica in SHFB, come alla tua seconda domanda.

Inoltre, è possibile utilizzare MAML entro SHFB per la documentazione concettuale, come ad esempio si parla come essere nel file doc / pdf. Dovreste essere in grado di utilizzare Doc2Maml per migrare il vostro attuale documentazione. Doc2Maml è una parte di DocProject, ma sembra che si potrebbe essere in grado di eseguirlo autonomo.

Modifica in risposta al commento:

Le indicazioni sono per SHFB 1.8.0.1. Non mi ricordo il modo esatto per farlo in 1.7, ma credo che sia simile:

1. In gruppo "Commenti" nella scheda Proprietà progetto, fare clic sui puntini di sospensione a destra del "NamespaceSummaries".
2. Nell'elenco casella in alto a sinistra, deselezionare qualsiasi spazio dei nomi che si desidera escludere.

Questa è anche la schermata in cui si mette sintesi dello spazio dei nomi in.

Answer 2

Oltre al Castello di sabbia, come già detto, vorrei anche raccomando guardando FxCop e StyleCop per contribuire a rendere che il proprio codice e la documentazione è fino a CLS Compliance norme.

Answer 3

Sandcastle Builder file di Guida (SHFB) si ha un file CHM, dove si possono trovare le risposte a domande come "come posso escludere alcuni spazi dei nomi o classi dalla doc generato?"

Si potrebbe pensare che conosco la risposta e mi viene snarky da non dire voi. Non vero. Ma ero sfiorando il doc di ieri sera e ho visto una voce su questo argomento.

Non so perché non sarebbe solo lasciare in roba VB e C ++; ci può in futuro essere qualcuno che usa un linguaggio che è (incredibilmente) non C # con la libreria. La lingua è normalmente impostabile con l'aiuto spettatore, in modo da C # sviluppatori possono ignorare la sintassi VB.

Per quanto riguarda la fusione, SHFB ha un meccanismo per aggiungere in HTML arbitrario in una gerarchia arbitraria. Nella GUI è qui:

http://www.freeimagehosting.net/uploads/7de19ea568.jpg

Con questo, si potrebbe convertire il PDF / DOC in HTML e poi semplicemente incorporare nel chm.