Documentar secciones
Cada sección del documento contiene información acerca de una clase o un módulo. Para introducir el componente puede escribir un bloque de sección. La descripción corta además se usa dentro de la tabla de contenidos. Todos los campos @ son opcionales.
/** * SECTION:meepapp * @short_description: the application class * @title: Meep application * @section_id: * @see_also: #MeepSettings * @stability: Stable * @include: meep/app.h * @image: application.png * * The application class handles ... */
- SECCIÓN <nombre>
-
El nombre enlaza la sección de la documentación con la parte respectiva en el archivo <paquete>-sections.txt. El nombre aquí proporcionado debería coincidir con la etiqueta <ARCHIVO> en el archivo <paquete>-sections.txt.
- @short_description
-
Una línea descrita en la sección, que después aparece tras los enlaces en el TOC y en la página de la sección.
- @title
-
De forma predeterminada el título de la sección es <name> de la declaración SECTION. Se puede sobrescribir con el campo @title.
- @section_id
-
Sobrescribe el uso del título como el identificador de sección. <title> se usa en GObjects como el identificador de sección (section_id) y para otra sección es <MÓDULO>-<title>.
- @see_also
-
Una lista de símbolos relacionados con esta sección.
- @stability
-
Esta API tiene una descripción informal del nivel de estabilidad. Se recomienda el uso de uno de estos términos:
- Estable: La intención de una interfaz estable es la de permitir que terceras partes arbitrarias desarrollen aplicaciones para esas interfaces, las liberen, y confíen que que se podrán ejecutar en todas las publicaciones menores del producto (después de que se introdujese la interfaz en una de ellas, y dentro de la misma versión principal de la publicación). Incluso en publicaciones importantes no se espera que existan cambios incompatibles, y de haberlos habrá buenas razones para ello.
- Inestable: Las interfaces inestables son experimentales o de transición. Generalmente se usan para dar a los desarrolladores externos acceso a tecnología nueva o cambiante, o para proporcionar una solución a un problema, anticipándose a una solución más general. No se realizan reclamaciones acerca de la compatibilidad del código o del binario desde una publicación menor a la siguiente.
- Privada: Una interfaz que se puede usar en la pila de GNOME en si misma, pero que no está documentada para usuarios finales. Tales funciones sólo se deberían usar de formas especificadas y documentadas.
- Interna: Una interfaz que es interna a un módulo y no requiere documentación para el usuario final. Se asume que las funciones que están sin documentar son internas.
- @include
-
Los archivos #include para mostrar en la sección del resumen (una lista separada por comas), sobrescribiendo el valor global del archivo de secciones o de la línea de comandos. Este elemento es opcional.
- @image
-
La imagen para mostrar en la parte superior de la página de referencia, para esta sección. Generalmente será un tipo de diagrama para ilustrar la apariencia visual de una clase o diagrama de su relación con otras clases. Este elemento es opcional.
Para evitar recompilaciones innecesarias después de cambios en la documentación ponga los documentos de sección en el código fuente C cuando sea posible.