Sandcastle non documenta Riepiloghi proprietà

Question

Sto utilizzando SandCastle con la GUI HelpBuilder per la prima volta oggi per aiutare a creare un'API di alcune delle nostre funzioni e proprietà esposte. Ho incluso /// <summary> ... </summary su un numero di proprietà in cui ritenevo che avrebbero tratto beneficio da una documentazione aggiuntiva o da esempi di utilizzo.

Quando si crea il file di output su chm, non vedo affatto le descrizioni di riepilogo. Tutti i membri della proprietà sono elencati, ma le loro descrizioni sono vuote. Ho ricostruito il progetto e provato alcune impostazioni diverse in SandCastle, ma non vengono ancora visualizzate.

C'è qualcosa di ovvio che sto trascurando? SandCastle non legge i riepiloghi delle proprietà? O i sommari hanno bisogno di una parola chiave diversa?

Answer 1

Dalla Sandcastle pagina Common Issues Aiuto:

codice mancante Commenti nella documentazione

Per impostazione predefinita, tutti i documenti XML di un progetto dovrebbe essere in un singolo file denominato, comments.xml. Se si dispone di più file di documentazione XML, inserirli in una nuova cartella denominata, Commenti e regolare sandcastle.config per utilizzare invece un carattere jolly, come nell'esempio seguente.

<!-- Copy in comments --> 
<component type="Microsoft.Ddue.Tools.CopyFromIndexComponent" 
      assembly="%DXROOT%\ProductionTools\BuildComponents.dll"> 
    <index name="comments" value="/doc/members/member" 
     key="@name" cache="100"> 
    <data base="%SystemRoot%\Microsoft.NET\Framework\v2.0.50727" 
      recurse="false" files="*.xml" /> 

    <data files="Comments\*.xml" /> <!-- This line was modified --> 

    </index> 
    <copy name="comments" source="*" target="/document/comments" /> 
<components> 

Per ulteriori informazioni, vedere this blog post.

Answer 2

si deve indicare a Visual Studio per generare il file di documentazione XML in fase di compilazione: basta impostare la proprietà di progetto corrispondente, come descritto qui: http://msdn.microsoft.com/en-us/library/vstudio/x4sa0ak0(v=vs.100).aspx

Dopo di che, Castello di sabbia emette i commenti "Sommario" nel " Descrizione "colonna.

Answer 3

Sembra che un'altra risposta fosse già accettata come funzionante, ma aggiungerò la mia soluzione poiché ho avuto lo stesso problema ma per un altro motivo.

Se si apre il file XML che si sta utilizzando come origine della documentazione, si controlla il metodo/proprietà per cui si sono scritti i commenti ma non viene visualizzato nel documento sandcastle finale. Se viene visualizzato il messaggio:

Badly formata commento XML ignorato per membro "M: ...

Poi, come me, probabilmente incluso alcuni caratteri che XML non ero troppo contento che ho usato il." & "in un commento, ma XML ti urlerà se utilizzi anche" < "o"> "Risolvi il tuo commento e dovresti essere pronto!