mozilla

Escribiendo documentación de referencia de la interfaz

Este artículo muestra como crear documentación para interfaces útiles y correctamente formateada. Cada interfaz debería estar documentada en su propio artículo, y siendo el título del artículo el nombre del interfaz.

Aprender mediante el ejemplo

Echa un vistazo a nuestro documento de muestra de interfaz para ver una interfaz ficticia que incluye todos los elementos de un documento completo de referencia de una interfaz. Este artículo puede servir de ejemplo cuando se documente una interfaz.

Hay algunas interfaces reales que observan este estándar, como por ejemplo nsIFeedProcessor, nsIFeedContainer, nsIFeedTextConstruct, y nsIScriptableUnescapeHTML.

Sección de referencia de interfaz

Cada artículo de referencia de interfaz tiene al menos una sección de introducción (que no tiene título o encabezado). La introducción debería aportar una visión de la utilidad de la interfaz.

Basándote en la lista de contenidos, usa la plantilla IFSummary para describir la localización y el estado del interfaz en el árbol de origen.

Los parámetros de la plantilla IFSummary son:

Ruta del archivo IDL que define la interfaz
Se usa para crear un vínculo con el IDL de la interfaz sobre el MXR para que el lector pueda referirse a él si lo desea.
Interfaz padre
Es el nombre de la interfaz sobre el que se basa la interfaz que se está documentando. Se convertirá en un vínculo a esa interfaz en la referencia y se mostrará.
scriptable/no scriptable
Una cadena que indica si la interfaz se puede convertir en un script o no. Debes elegir "scriptable" o "no scriptable" (que diferencian entre mayúsculas y minúsculas). La indicación se convertirá en el marcador apropiado, de color gris cuando la interfaz se pueda convertir en script y rojo cuando no. El indicador también incluirá un vínculo a un artículo que explique lo que significa esto.
Últimos cambios en una versión Gecko
Es una cadena que indica la versión de Gecko en la que la interfaz sufrió cambios por última vez. Debería ser una cadena con el formato estandar de la versión de Gecko, como "1.9" o "1.9.2" o incluso "1.9.1.6".
ResumenOptional
Un breve resumen de texto de lo que la interfaz hace. Basta con una frase o dos. Esto es sólo opcional por compatibilidad hacia atrás con documentos de interfaces antiguas que usan la plantilla ya relegada de InterfaceStatus (que ahora dirige a esta). Siempre deberías incluirlo.
Versión introducida Optional
Si sabes la versión de Gecko en la que se introdujo la interfaz, inclúyela aquí. Esto dará lugar para la inclusión de una versión de línea de tiempo, mostrando la disponibilidad de la interfaz en contraste con el historial de Gecko, de manera gráfica.
Versión rechazada Optional
Si la versión es rechazada, incluyela aquí. Esta será usada cuando se elabore el diagrama de la versión de línea de tiempo.
Versión obsoleta Optional
De manera similar, si la interfaz es obsoleta y ya no está disponible en su totalidad, incluye la versión Gecko en la que se llevaría a cabo.
FIXME: Debería describir la sección 'Implementado por'  aquí

Todas las demás secciones son opcionales, y si alguna de ellas es necesaria variará de una interfaz a otra. Las secciones opcionales son:

Visión de Métodos

La visión de conjunto de métodos es una tabla que simplemente lista todas las firmas de métodos para cada método proveniente de la interfaz. Se debe poder hacer clic sobre el nombre del método como un enlace hacia la descripción del propio método. Idealmente, los métodos deben ser listados en orden alfabético.

Si un método soporta multiples tipos para un parámetro dado, puedes listarlo usando el formato [type1, type2, ..., typeN].

Atributos

Las secciones de atributos consisten en una tabla de tres columnas. La primer columna contiene los nombres de cada atributo ofrecido por la interfaz. La segunda columna indica los tipos de cada atributo; estos tipos deben ser enlaces para non-simple tipos. La tercer columna debe describir al atributo, explicando su uso y proporcionando cualquier detalle necesario. Por favor lista los atributos en orden alfabético; puedes ordenar la tabla después de haber terminado haciendo clic derecho sobre ella; hay una opción de "Ordenar tabla" en el menu contextual.

Constantes

Cada grupo de constantes debe tener una sub-sección que contenga una tabla que describa a las constantes relevantes. La tabla debe tener tres columnas: Constante (los nombres de las constantes), Valor (sus valores), y Descripción (texto descripitivo explicando el uso de la constante).

Métodos

La sección de métodos provée documentación detallada para cada método ofrecido por la interfaz. Dentro de la sección de métodos debe de haber una sub-sección para cada método. Cada nombre de sub-sección de método debe incluír paréntesis de cerrado (como "parseAsync()" en la nsIFeedProcessor interfaz de referencia.

Los métodos deben ser listados en el mismo orden en que aparecen en la sección de "Vista de métodos".

Cada sub-sección de método debe comenzar con una descripción de lo que el método hace, seguido por la actual firma de método. Cada parámetro hacia el método debe de estar en una línea separada para tener cladidad. 

Después de la firma de método debe venir la sección de "Parámetros". Con el fin de evitar llenar la tabla de de contenidos para la página, usamos  <h5>Parameters</h5> para definir la sub-sección de cabecera de Parametros.

Los parámetros son después listados con descripciones de cada parámetro usando el formato de definición de lista. Si no hay parámetros, escribe la palabra 'None' debajo de la cabecera de Parámetros.

Si el método regresa un valor, incluye una sub-sección de "Return value", usando la forma <h5>Return value</h5>. Esta sub-sección debe explicar de forma simple el valor de respuesta, su tipo, y si aplica, sus posibles valores.

Si el método puede lanzar excepciones, una sub-sección similar a "Exceptions thrown" debe de ser incluída, conteniendo una lista de definición de estilo de lista, para cada posible excepción.

Para un buen ejemplo de una sección de método que incluya todas las sub-secciones, véase el nsIScriptableUnescapeHTML.parseFragment() método.

Observaciones

Cualquier comentario general que aplique a la interfaz en un todo,debe ser colocado en la sección de "Observaciones".

Ver también

Si enlaces hacia otras interfaces, o hacia algún otro documento, pudieran ser de ayuda para el lector, estos deberán ser listados en la sección "Ver también".

Categorización de articulos

Cada artículo que documente una interfaz necesita ser añadido a la categoría de Interfaces agregando la etiqueta "Interfaces". De la misma manera, el artículo debe tener cualquier otra etiqueta apropiada.

Otras plantillas útiles 

Haz uso de las MDC:Plantillas Personalizadas cuando sea apropiado, en particular, la Plantilla:interfaz cuando se enlace hacia otras interfaces, y Plantilla:métodointerfaz cuando se enlace a un método en particular u otra interfaz.

Encontrar artículos que necesitan ayuda 

Date un paseo por la lista de interfaces y mira si alguna está marcada en la categoría NecesitaTrabajo. Estas son interfaces que se conoce que necesitan ser formateadas al nuevo plan. Si modificas una, remueve la línea que las agrega a esta categoría. 

Etiquetas y colaboradores del documento

Contributors to this page: maedca, Aligo, LuisArt
Última actualización por: LuisArt,