autogsdoc - Generador de documentación API GNUstep y convertidor XML->HTML
autogsdoc [-Files filename] [-GenerateHtml YES|no] [-Clean yes|NO] [-CleanTemplates yes|NO] [-IgnoreDependencies yes|NO] [-MakeDependencies yes|NO] [-ShowDependencies yes|NO] [-HeaderDirectory path] [-DocumentationDirectory path] [-Declared location] [-Project title] [-Standards yes|NO] [-DocumentAllInstanceVariables yes|NO] [-DocumentInstanceVariables YES|no] [-InstanceVariablesAtEnd yes|NO] [-ConstantsTemplate filename] [-FunctionsTemplate filename] [-MacrosTemplate filename] [-TypedefsTemplate filename] [-VariablesTemplate filename] [-SystemProjects string] [-LocalProjects string] [-Projects dictString] [-Verbose yes|NO] [-Warn yes|NO] [-WordMap dictString] [files]
La herramienta autogsdoc es una utilidad de línea de comandos que ayuda a los desarrolladores a producir documentación de referencia para las API de GNUstep. También permite a los desarrolladores escribir y mantener otra documentación en XML y convertirla a HTML. En detalle, autogsdoc:
Extraiga comentarios especiales que describan las interfaces públicas de clases, categorías, protocolos, funciones y macros del código fuente de Objective C (archivos de encabezado y, opcionalmente, archivos fuente) en archivos GSDoc XML.
Convierta archivos XML de GSDoc, ya sea generados a partir del código fuente o escritos manualmente por desarrolladores, en HTML.
Cree índices basados en conjuntos de archivos XML de GSDoc y conviértalos también a HTML.
El uso más común es ejecutar el comando con uno o más nombres de archivo de encabezado como argumentos... la herramienta analizará automáticamente los archivos de origen correspondientes en el mismo directorio que los encabezados (o el directorio actual, o el directorio especificado usando DocumentationDirectory predeterminado) y producir archivos GSDoc y HTML como salida. Para obtener los mejores resultados, este modo debe ejecutarse desde el directorio que contiene los archivos de origen. (Tenga en cuenta que, dado que C es un subconjunto de Objective C, esta herramienta puede funcionar para documentar funciones y otras estructuras de C en un código C simple).
Los archivos GSDoc también se pueden proporcionar directamente o por sí solos, y se convertirán a HTML. Consulte la documentación HTML de GSDoc o la página del comando man gsdoc(7) para obtener información sobre el formato GSDoc.
Finalmente, los archivos HTML se pueden proporcionar en la línea de comando. Las referencias cruzadas a otras partes de la documentación del código que se encuentran dentro de ellas se reescribirán en función de lo que se encuentra actualmente en el proyecto.
El analizador de código fuente producirá automáticamente documentos GSDoc que enumeran los métodos en las clases que se encuentran en los archivos fuente, e incluirá texto de comentarios con formato especial de los archivos fuente.
Cualquier comentario que comience con una barra oblicua y dos asteriscos en lugar de la barra oblicua común y un solo asterisco, se toma como marcado GSDoc, para usarse como la descripción de la clase o el método que lo sigue. Este texto de comentario se reformatea y luego se inserta en la salida.
Cuando varios comentarios están asociados con el mismo elemento, se unen con un salto de línea (
) entre cada uno si es necesario.La herramienta se puede usar fácilmente para documentar programas y bibliotecas, simplemente dándole el nombre del archivo fuente que contiene la función main() del programa; toma los comentarios especiales de esa función y los maneja especialmente, insertándolos como una sección al final del primer capítulo del documento (crea el primer capítulo si es necesario).
Las opciones se describen en la sección Argumentos y valores predeterminados a continuación.
Hay algunos casos en los que se realiza un procesamiento adicional especial, predominantemente en el primer comentario que se encuentra en el archivo de origen, desde el cual se pueden extraer varios fragmentos del marcado GSDoc y colocarlos en las ubicaciones adecuadas en el documento de salida:
En cualquier línea donde se encuentre AutogsdocSource:, el resto de la línea se toma como un nombre de archivo de origen que se utilizará en lugar de suponer que cada archivo .h procesado utiliza un archivo .m del mismo nombre. Puede proporcionar múltiples líneas AutogsdocSource: donde un archivo de encabezado declara elementos que están definidos en múltiples archivos fuente. Si un nombre de archivo es absoluto, se usa tal como se proporcionó. Si, por el contrario, es una ruta relativa, el software busca el archivo de origen primero en relación con la ubicación del archivo de cabecera, y si no lo encuentra allí, en relación con el directorio actual en el que se ejecuta autogsdoc, y finalmente en relación con el directorio especificado por DocumentationDirectory por defecto.
Un resumen del contenido del documento... colocado en el encabezado de la salida de GSDoc.
Una descripción del autor del código: se puede repetir para manejar el caso en el que un documento tiene varios autores. Colocado en el encabezado de la salida de GSDoc. Como ayuda para la legibilidad de la fuente, se realiza un procesamiento adicional especial relacionado con el autor del documento - Cualquier línea del formulario
nombre
nombre
nombre' o
name' se reconocerá y se convertirá en un elemento author, que posiblemente contenga un elemento email.
Colocado en la salida de GSDoc justo antes del final del cuerpo del documento, destinado a ser utilizado para apéndices, índices, etc.
Colocado inmediatamente antes de cualquier documentación de clase generada ... destinado a ser utilizado para proporcionar una descripción general de cómo funciona el código que se documenta. Cualquier documentación para la función main() de un programa se inserta como una sección al final de este capítulo.
Copyright del contenido del documento ... colocado en el encabezado de la salida de GSDoc. Como ayuda para la legibilidad de la fuente, se realiza un procesamiento adicional especial: cualquier línea del formulario 'Texto de derechos de autor (C)' se reconocerá y se convertirá en un elemento copiar.
Fecha de la revisión del documento ... colocada en el encabezado de la salida GSDoc. Si se omite, la herramienta intentará construir un valor a partir de la etiqueta de fecha RCS (si está disponible).
Insertado en el documento al comienzo del cuerpo ... destinado a proporcionar páginas de introducción o contenido, etc.
Título del documento ... colocado en el encabezado de la salida de GSDoc. Si se omite, la herramienta generará un título propio (probablemente pobre), por lo que debe incluir este marcado manualmente.
Identificador de versión del documento ... colocado en el encabezado de la salida GSDoc. Si se omite, la herramienta intentará construir un valor a partir de la etiqueta RCS Revision (si está disponible).
NB El marcado que se acaba de describir puede usarse dentro de la documentación de clase, categoría o protocolo... si es así, se extrae y envuelve el resto de la documentación para la clase como el capítulo de la clase. El resto de la documentación de la clase normalmente se inserta al final del capítulo, pero puede sustituirse en lugar del pseudoelemento
En los comentarios que se utilizan para proporcionar texto para la descripción de un método, el siguiente marcado se elimina del texto y se maneja especialmente:
El método se marca como el inicializador designado para la clase.
El método está marcado como uno que las subclases deben anular (por ejemplo, un método abstracto).
El método está marcado como uno que las subclases NO deben anular.
El marcado se elimina de la descripción y se coloca después en la salida de GSDoc, de modo que el método se describe como conforme (o no conforme) con los estándares especificados.
Generalmente, el texto en los comentarios se reformatea para estandarizarlo y sangrar bien... el reformateo no se realiza en ningún texto dentro de un elemento
Ciertas constantes bien conocidas como YES, NO y nil están encerradas en el marcado ... .
Los nombres de los argumentos de los métodos dentro de las descripciones de los métodos se incluyen en el marcado ... .
Los nombres de los métodos (que comienzan con un signo más o menos) se incluyen en el marcado
Los especificadores de métodos, incluidos los nombres de clase (que comienzan y terminan con corchetes) se incluyen en el marcado
Los nombres de funciones (que terminan en '()') que no sean 'main()' se incluyen en el marcado
La herramienta acepta ciertos valores predeterminados del usuario (que, por supuesto, se pueden proporcionar como argumentos de la línea de comandos anteponiendo '-' antes del nombre predeterminado y dando el valor después, como en -Clean YES):
Si este valor booleano se establece en SÍ, en lugar de generar documentación, la herramienta elimina todos los archivos GSDoc generados en el proyecto y todos los archivos html generados a partir de ellos (así como los que se generarían a partir de los archivos GSDoc enumerados explícitamente), y finalmente elimina el archivo de índice del proyecto. La única excepción a esto es que los archivos GSDoc de plantilla (es decir, los especificados con los argumentos "-ConstantsTemplate...", "-FunctionsTemplate...", etc.) no se eliminan a menos que se establezca el indicador CleanTemplates.
Este indicador especifica si los archivos de plantilla GSDoc deben eliminarse junto con otros archivos cuando se especifica la opción Limpiar. El valor predeterminado es que no se eliminen... ya que es posible que estas plantillas se hayan producido manualmente y solo se hayan insertado datos en ellas.
Especifique el nombre de un documento de plantilla en el que se debe insertar documentación sobre constantes de todos los archivos del proyecto. Esto es útil si las constantes en el código fuente están dispersas en muchos archivos y necesita agruparlas en un solo lugar. Usted es responsable de asegurarse de que el documento de plantilla básico (en el que se inserta la documentación constante individual) contenga toda la demás información que desee, pero para su comodidad, autogsdoc generará una plantilla simple (que luego puede editar) para usted si el archivo no lo hace. no existe. La inserción tiene lugar inmediatamente antes del elemento back (o si no existe, inmediatamente antes del final del elemento body) en la plantilla.
Especifique dónde se deben documentar los encabezados como encontrados. El nombre real producido en la documentación se forma agregando el último componente del nombre del archivo de encabezado al valor de este valor predeterminado. Si no se especifica este valor predeterminado, se utiliza el nombre completo del archivo de encabezado (tal como se proporciona en la línea de comandos), con el valor predeterminado de HeaderDirectory antepuesto. Un uso típico de esto podría ser '"-Base declarada"' al generar documentación para la biblioteca base de GNUstep. Esto daría como resultado que la documentación diga que NSString se declara en 'Foundation/NSString.h'
Esta bandera le permite generar documentación para todas las variables de instancia. Normalmente, solo se documentarán aquellos declarados explícitamente 'públicos' o 'protegidos'.
Este indicador le permite desactivar completamente la documentación de las variables de instancia. Normalmente, se documentarán las variables de instancia 'públicas' o 'protegidas' explícitamente declaradas.
Esta bandera, si está establecida, indica al generador de HTML que coloque la documentación de la variable de instancia al final de la clase, en lugar de al principio. Esto es útil si usa muchas variables de instancia protegidas que solo serán de interés secundario para los usuarios generales de la clase.
Puede usarse para especificar el directorio en el que se colocará la documentación generada. Si esto no está configurado, la salida se coloca en el directorio actual. Este directorio también se usa como último recurso para ubicar los archivos de origen (no los encabezados) y, lo que es más importante, se usa como el primer y único recurso para ubicar los archivos .gsdoc que se pasan en el línea de comando. Cualquier información de ruta proporcionada para estos archivos se elimina y se buscan en 'DocumentationDirectory' (aunque es posible que no se hayan generado automáticamente).
Especifica el nombre de un archivo que contiene una lista de nombres de archivo como un formato de matriz de lista de propiedades (name1,name2,...). Si está presente, los nombres de archivo en la lista de argumentos del programa se ignoran y los nombres en este archivo se usan como la lista de nombres para procesar.
Especifique el nombre de un documento de plantilla en el que se debe insertar la documentación sobre las funciones de todos los archivos del proyecto. Esto es útil si el código fuente de la función está disperso en muchos archivos y necesita agruparlo en un solo lugar. Usted es responsable de asegurarse de que el documento de plantilla básico (en el que se inserta la documentación de la función individual) contenga toda la información que desea, pero para su comodidad, autogsdoc generará una plantilla simple (que luego puede editar) para usted si el archivo no lo hace. no existe. La inserción tiene lugar inmediatamente antes del elemento back (o si no existe, inmediatamente antes del final del elemento body) en la plantilla.
Puede usarse para especificar si se generará una salida HTML. El valor predeterminado es SÍ.
Puede usarse para especificar el directorio en el que se buscarán los archivos de encabezado. Cuando se proporciona, este valor se antepone a los nombres de encabezados relativos; de lo contrario, los nombres de encabezados relativos se interpretan en relación con el directorio actual. Los archivos de encabezado especificados como rutas absolutas no se ven afectados por este valor predeterminado.
Un valor booleano que se puede usar para especificar que el programa debe ignorar los tiempos de modificación de archivos y regenerar archivos de todos modos. Proporcionado para su uso junto con el sistema 'make', que se espera que gestione la comprobación de dependencias por sí mismo.
Este valor se utiliza para controlar la inclusión automática de proyectos externos locales en el sistema de indexación para la generación de referencias cruzadas en la salida del documento final. Si se establece en 'Ninguno', no se realizan referencias de proyectos locales; de lo contrario, se busca recursivamente el directorio de documentación de GNUstep 'Local' para archivos con una extensión '.igsdoc', y se utiliza la información de indexación de esos archivos. El valor de esta cadena también se usa para generar los nombres de archivo en la referencia cruzada... si es una cadena vacía, se supone que la ruta a usar es un archivo en el mismo directorio donde se encontró el archivo igsdoc, de lo contrario es se utiliza como prefijo del nombre en el índice. NÓTESE BIEN. Los proyectos locales con el mismo nombre que el proyecto que se está documentando actualmente no serán incluidos en este mecanismo. Si desea incluir tales proyectos, debe hacerlo explícitamente usando -Proyectos...
Especifique el nombre de un documento de plantilla en el que se debe insertar documentación sobre macros de todos los archivos del proyecto. Esto es útil si el código de macro está disperso en muchos archivos y necesita agruparlo en un solo lugar. Usted es responsable de asegurarse de que el documento de plantilla básico (en el que se inserta la documentación de macro individual) contenga toda la demás información que desee, pero para su comodidad, autogsdoc generará una plantilla simple (que luego puede editar) para usted si el archivo no lo hace. no existe. La inserción tiene lugar inmediatamente antes del elemento back (o si no existe, inmediatamente antes del final del elemento body) en la plantilla.
Un nombre de archivo que se usará para generar información de dependencia para make. Esto tomará la forma de una lista de todos los archivos de encabezado y fuente conocidos para el proyecto como dependencias del nombre del proyecto (ver 'Proyecto').
Puede usarse para especificar el nombre de este proyecto... determina el nombre del archivo de referencia de índice producido como parte de la documentación para proporcionar información que permita a otros proyectos hacer referencias cruzadas a los elementos de este proyecto.
Este valor se puede proporcionar como un diccionario que contiene las rutas a los archivos de referencia/índice igsdoc utilizados por proyectos externos, junto con los valores que se utilizarán para asignar los nombres de archivo que se encuentran en los índices. Por ejemplo, si un archivo de índice de proyecto (igsdoc) dice que la clase 'Foo' se encuentra en el archivo 'Foo', y la ruta asociada con ese índice de proyecto es '/usr/share/doc/proj', luego se genera html la salida puede hacer referencia a la clase como si estuviera en '/usr/share/doc/prj/Foo.html' . Tenga en cuenta que se puede proporcionar un diccionario en la línea de comando usando el formato PropertyList estándar (no el formato XML de OS X), usando punto y coma como separadores de línea y encerrándolo entre comillas simples.
Un valor booleano que se puede usar para especificar que el programa debe registrar qué archivos se están regenerando debido a sus dependencias con otros archivos.
Un valor booleano utilizado para especificar si el programa debe insertar información sobre el cumplimiento de los estándares en la documentación. Esto solo debe usarse al documentar las bibliotecas y herramientas de GNUstep, ya que asume que el código que se documenta es parte de GNUstep y posiblemente cumple con el estándar OpenStep o implementa métodos compatibles con MacOS-X.
Este valor se utiliza para controlar la inclusión automática de proyectos externos al sistema en el sistema de indexación para la generación de referencias cruzadas en la salida del documento final. Si se establece en 'Ninguno', no se realizan referencias a proyectos del sistema; de lo contrario, se busca recursivamente el directorio de documentación de GNUstep 'Sistema' en busca de archivos con una extensión '.igsdoc', y se utiliza la información de indexación de esos archivos. El valor de esta cadena también se usa para generar los nombres de archivo en la referencia cruzada... si es una cadena vacía, se supone que la ruta a usar es un archivo en el mismo directorio donde se encontró el archivo igsdoc, de lo contrario es se utiliza como prefijo del nombre en el índice. NÓTESE BIEN. Los proyectos del sistema con el mismo nombre que el proyecto que se está documentando actualmente no serán incluidos en este mecanismo. Si desea incluir tales proyectos, debe hacerlo explícitamente usando -Proyectos...
Especifique el nombre de un documento de plantilla en el que se debe insertar la documentación sobre typedefs de todos los archivos del proyecto. Esto es útil si el código fuente de typedef está disperso en muchos archivos y necesita agruparlo en un solo lugar. Usted es responsable de asegurarse de que el documento de plantilla básico (en el que se inserta la documentación typedef individual) contenga toda la demás información que desee, pero para su comodidad, autogsdoc generará una plantilla simple (que luego puede editar) para usted si el archivo no lo hace. no existe. La inserción tiene lugar inmediatamente antes del elemento back (o si no existe, inmediatamente antes del final del elemento body) en la plantilla.
Una cadena utilizada para proporcionar el nombre que se utilizará en el enlace 'hacia arriba' de los documentos GSDoc generados. Normalmente debería ser el nombre de un archivo que contiene un índice de los contenidos de un proyecto. Si falta o se establece en una cadena vacía, no se proporcionará ningún enlace 'hacia arriba' en los documentos.
Especifique el nombre de un documento de plantilla en el que se debe insertar la documentación sobre las variables de todos los archivos del proyecto. Esto es útil si el código fuente variable está disperso en muchos archivos y necesita agruparlo en un solo lugar. Usted es responsable de asegurarse de que el documento de plantilla básico (en el que se inserta la documentación de las variables individuales) contenga toda la demás información que desee, pero para su comodidad, autogsdoc generará una plantilla simple (que luego puede editar) para usted si el archivo no lo hace. no existe. La inserción tiene lugar inmediatamente antes del elemento back (o si no existe, inmediatamente antes del final del elemento body) en la plantilla.
Un valor booleano que se usa para especificar si desea que se produzca una salida detallada de depuración/advertencia.
Un booleano que se usa para especificar si desea que se produzca una salida de advertencia estándar (por ejemplo, un informe de métodos no documentados).
Este valor es un diccionario que se utiliza para asignar identificadores/palabras clave que se encuentran en los archivos de origen a otras palabras. Por lo general, no tendrá que usar esto, pero a veces es útil evitar que el analizador se confunda con el uso de macros de preprocesador C. Puede redefinir efectivamente la macro a algo menos confuso. El valor al que asigne el identificador debe ser uno de: otro identificador, una cadena vacía: el valor se ignora, dos barras inclinadas ('//'): el resto de la línea se ignora. Tenga en cuenta que se puede proporcionar un diccionario en la línea de comando usando el formato PropertyList estándar (no el formato XML de OS X), usando punto y coma como separadores de línea y encerrándolo entre comillas simples.
El valor predeterminado 'Arriba' se usa para especificar el nombre de un documento que debe usarse como enlace 'arriba' para cualquier otro documento que se use. Este nombre no debe incluir una ruta o extensión. En general, el documento al que se hace referencia por defecto debe ser un documento GSDoc editado a mano que debe tener una sección atrás que contenga un índice de proyecto. p.ej.
<?xml version="1.0"?>
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 1.0.3//EN"
"http://www.gnustep.org/gsdoc-1_0_3.xml">
<gsdoc base="index">
<head>
<title>My project reference</title>
<author name="my name"></author>
</head>
<body>
<chapter>
<heading>My project reference</heading>
</chapter>
<back>
<index scope="project" type="title" />
</back>
</body>
</gsdoc> Source: .h, .m, .c
GSDoc: .gsdoc
Index: .igsdoc
HTML: .htmlVarios elementos de GSDoc aún no se representan correctamente en HTML. Estos son:
Los mensajes de error y las advertencias pueden provenir de cada una de las etapas de la canalización: control de nivel superior, análisis de origen, análisis de GSDoc e indexación.
gsdoc(7), GNUstep(7)
Autogsdoc combinó las capacidades de dos herramientas anteriores, 'autodoc' y 'gsdoc', que realizaban las traducciones source->GSDoc y GSDoc->HTML respectivamente. Estas herramientas anteriores y el formato GSDoc se desarrollaron para GNUstep basándose en el lenguaje GDML SGML anterior.
Esta página de manual apareció por primera vez en gnustep-base 1.9.2 (marzo de 2004).
autogsdoc fue escrito por Richard Frith-Macdonald rfm@gnu.org
Esta página del manual fue añadida por Adrian Robert arobert@cogsci.ucsd.edu.