Documentación
La documentación de un esquema consiste en añadir información adicional sobre el esquema, como comentarios, información de autoría o versiones.
Podemos pensar que un método para añadir esta información es utilizar comentarios. El problema es que los analizadores no garantizan que los comentarios no se modifiquen al procesar los documentos y, por tanto, que los datos añadidos no se pierdan en algún proceso de transformación del documento.
annotation
En lugar de usar los comentarios, XML Schema tiene definido un elemento annotation que permite guardar información adicional. El elemento annotation se coloca como hijo de los elementos a documentar, como elementos, atributos, tipos de datos y reglas de validación.
Este elemento, a su vez, puede contener una combinación de otros:
documentationappinfo
documentation
El elemento documentation se utiliza para proporcionar información de documentación humanamente legible sobre el esquema o una parte específica del esquema. Puede contener elementos XSD y elementos XML.
También permite determinar el idioma del documento mediante el atributo xml:lang.
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="software" type="tipo-software">
<xs:annotation>
<xs:documentation xml:lang="es-es"><b>Nombre</b> del editor de texto.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:complexType name="tipo-software">
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="os" type="xs:string">
<xs:annotation>
<xs:documentation xml:lang="es-es">Sistemas operativos soportados.</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:schema>
En Visual Studio Code, cuando se pone el cursor encima del elemento <software> del documento XML se muestra lo siguiente:
Como se puede observar, se muestra el contenido del elemento documentation del XSD asociado al elemento software.
Por otro lado, cuando se pone el cursor encima del atributo os del documento XML se muestra lo siguiente:
En esta ocasión, como se puede observar, se muestra el contenido del elemento documentation del XSD asociado al atributo os.
El elemento documentation soporta algunos elementos HTML en el contenido.
appinfo
El elemento appinfo se utiliza para proporcionar información adicional. Esta información será utilizada por una aplicación para mostrar una ayuda contextual para elementos y atributos declarados en el esquema.
La información en appinfo no es necesariamente legible para un ser humano y puede contener instrucciones para una aplicación específica o una herramienta de procesamiento.
Un ejemplo de un XSD documentado sería el siguiente:
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="software" type="tipo-software">
<xs:annotation>
<xs:appinfo>Nombre del editor de texto.</xs:appinfo>
</xs:annotation>
</xs:element>
<xs:complexType name="tipo-software">
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="os" type="xs:string">
<xs:annotation>
<xs:appinfo>Sistemas operativos soportados.</xs:appinfo>
</xs:annotation>
</xs:attribute>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:schema>
En Visual Studio Code, cuando se pone el cursor encima del elemento <software> del documento XML se muestra lo siguiente:
Como se puede observar, se muestra el contenido del elemento appinfo del XSD asociado al elemento software.
Por otro lado, cuando se pone el cursor encima del atributo os del documento XML se muestra lo siguiente:
En esta ocasión, como se puede observar, se muestra el contenido del elemento appinfo del XSD asociado al atributo os.
Para que un appinfo se muestre en la ayuda contextual de Visual Studio Code, el contenido del elemento debe ser simple (no puede contener otros elementos).