Separación entre documentación XML y código fuente

 

A veces puede que interesar incrustar toda la documentación en el mismo fichero que el  código fuente, por ejemplo si se desea reusarla en múltiples fuentes o si es muy voluminosa e incluirla en el fuente dificultaría su legibilidad. Para estos casos se da la posiblidad  de dejar la documentación en un fichero XML aparte y referenciarla en el código fuente a través de la etiqueta de documentación <include>, que su usa así:

 

            <include file=”<nombreFichero>” path=”<rutaDocumentación>”/>

 

Cuando el compilador encuentre esta etiqueta al generar la documentación lo que hará será tratarla como si fuese la etiqueta del fichero <nombreFichero> indicada por la expresión XPath[1] <rutaDocumentación> Por ejemplo, si se tiene el código:

 

            /// <include file=”otro.xml” path=”Miembros/Miembro[@nombre=”A”]/*”/>

            class A

            {}

 

En este uso de <include> se está indicando que se ha de insertar todo el contenido de la etiqueta <Miembro> contenida en <Miembros> cuyo atributo nombre valga A. Luego, si el contenido del fichero otro.xml es de la forma:

 

            <Miembros>

                        ...

                        <Miembro name=”A”>

                                   <remarks>

Ejemplo de inclusión de documentación XML externa </remarks>

                                   <example>

                                               Para crear un objeto de esta clase usar:

                                                           <code>

                                                                       A obj = new A();

                                                           </code>

                                   </example>

                        </Miembro>

                        ...

            </Miembros>   

 

Entonces, el compilador generará documentación como si el fuente contuviese::

                                  

            /// <remarks>

///         Ejemplo de inclusión de documentación XML externa

/// </remarks>

            /// <example>

            ///         Para crear un objeto de esta clase usar:

            ///         <code>

            ///                     A obj = new A();

            ///         </code>

            /// </example>

            class A

            {}