Sandcastle no documenta los resúmenes de propiedad

Question

Estoy utilizando SandCastle con la GUI de HelpBuilder por primera vez hoy para ayudar a crear una API de algunas de nuestras funciones y propiedades expuestas. He incluido /// <summary> ... </summary en una serie de propiedades en las que sentí que se beneficiarían de una documentación adicional o ejemplos de uso.

Cuando construyo el archivo de salida en chm, no veo las descripciones de resumen en absoluto. Todos los miembros de la propiedad están en la lista, pero sus descripciones están en blanco. Reconstruí el proyecto y probé algunas configuraciones diferentes en SandCastle, pero todavía no se muestran.

¿Hay algo obvio que estoy pasando por alto? ¿SandCastle no lee los resúmenes de propiedades? ¿O los resúmenes necesitan una palabra clave diferente?

Answer 1

Desde el castillo de arena Common Issues página Ayuda:

Falta el código Los comentarios en Documentación

Por defecto, todos los documentos XML de un proyecto se espera que sea en un solo archivo llamado, comments.xml. Si tiene varios archivos de documentación XML, colóquelos en una nueva carpeta llamada, Comentarios y ajuste sandcastle.config para usar un comodín en su lugar, como en el siguiente ejemplo.

<!-- 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> 

Para obtener más información, consulte this blog post.

Answer 2

usted tiene que decir Visual Studio para generar el archivo de documentación XML en tiempo de compilación: acaba de establecer la propiedad del proyecto correspondiente a la descrita aquí: http://msdn.microsoft.com/en-us/library/vstudio/x4sa0ak0(v=vs.100).aspx

Después de eso, Castillo de arena dará salida a los comentarios "Resumen" en el " Descripción "columna.

Answer 3

Parece que ya se ha aceptado que otra respuesta funciona, pero voy a agregar mi solución ya que tuve el mismo problema pero por otra razón.

Si abre el archivo XML que está utilizando como su fuente de documentación, controle el método/propiedad para el que escribió los comentarios pero no aparece en su documento final de sandcastle. Si aparece el mensaje:

comentario XML mal formados ignorado por miembro de "M: ...

Entonces, como yo, es probable que incluyen algunos caracteres que XML no estaba muy contento con utilicé el". & "en un comentario, pero XML le gritará si usa también" < "o"> ". Corrija su comentario y ¡debería estar listo!