5.3 Unidades de información

Se utilizan varios entornos para describir servicios específicos proporcionados por los módulos. Los parámetros de cada entorno proporcionan información básica sobre lo que se está describiendo y su contenido proporciona la descripción. La mayoría de estos entornos generan entradas en el índice general (si se genera para el documento en cuestión). Si no se desea generar entradas en el índice, se dispone de variaciones del entorno que no lo hacen. Los entornos tienen nombres del estilo de serviciodesc, siendo la variante que no genera índice serviciodescni. La lista posterior incluye explícitamente las variantes disponibles.

Para cada uno de estos entornos, el primer parámetro, nombre, proporciona el nombre mediante el cual se accede al servicio.

Los entornos que describen servicios de los objetos dentro de un módulo, tales como métodos o atributos, permiten un parámetro opcional nombre de tipo. Cuando el servicio es un atributo de instancias de clase, sólo es necesario proporcionar nombre de tipo si la clase no ha sido la última en definirse en el módulo, ya que el valor nombre de la última \classdesc se usa por omisión. En el caso de los servicios de tipos internos o de extensión, se debe proporcionar siempre el nombre de tipo. Otro caso especial lo constituyen los métodos y miembros de ``protocolos'' generales, como los protocolos de formato y escritura descritos en el módulo formatter: Éstos pueden documentarse sin ninguna clase de implementación y siempre necesitarán el parámetro nombre de tipo.

\begin{datadesc} {nombre} \end{datadesc}: Este entorno se usa para documentar los datos globales de un módulo, incluyendo tanto variables como valores utilizados como ``constantes definidas''. Este entorno no se usa para documentar las clases y atributos del objeto.

\begin{datadescni} {nombre} \end{datadescni}: Como \datadesc, pero no afecta al índice.

\begin{excdesc} {nombre} \end{excdesc}: Describe una excepción.

\begin{funcdesc} {nombre}{parámetros} \end{funcdesc}: Describe una función al nivel del módulo. Los parámetros no deberían incluir los paréntesis de la sintaxis de llamada. Los métodos de los objetos no se documentan con este entorno. Sí se documentan con este entorno los métodos de objetos enlazados colocados en el espacio nominal del módulo como parte de su interfaz pública, ya que equivalen a funciones normales para la mayoría de los propósitos.
La descripción debería incluir información sobre los parámetros requeridos y cómo se usan (especialmente si se modifican los objetos mutables pasados como parámetros), los efectos secundarios y posibles excepciones. Se puede añadir un pequeño ejemplo.

\begin{funcdescni} {nombre}{parámetros} \end{funcdescni}: Como \funcdesc, pero no afecta al índice.

\begin{classdesc} {nombre}{parámetros del constructor} \end{classdesc}: Describe una clase y su constructor. Los parámetros del constructor no deben incluir el parámetro self ni los paréntesis de la sintaxis de llamada.

\begin{memberdesc} [nombre de tipo]{nombre} \end{memberdesc}: Describe un atributo del objeto. La descripción debe incluir información del tipo de dato esperado y si se puede cambiar directamente.

\begin{memberdescni} [nombre de tipo]{nombre} \end{memberdescni}: Como \memberdesc, pero no afecta al índice.

\begin{methoddesc} [nombre de tipo]{nombre}{parámetros} \end{methoddesc}: Describe un método del objeto. Los parámetros no deben incluir el parámetro self ni los paréntesis de la sintaxis de llamada. La descripción debe incluir información análoga a la descrita en \funcdesc.

\begin{methoddescni} [nombre de tipo]{nombre}{parámetros} \end{methoddescni}: Como \methoddesc, pero no afecta al índice.

Ver Sobre este documento... para obtener información sobre sugerencias.