Este es el comando autogsdoc que se puede ejecutar en el proveedor de alojamiento gratuito de OnWorks utilizando una de nuestras múltiples estaciones de trabajo en línea gratuitas, como Ubuntu Online, Fedora Online, emulador en línea de Windows o emulador en línea de MAC OS.
PROGRAMA:
NOMBRE
autogsdoc - Generador de documentación GNUstep API y convertidor XML-> HTML
SINOPSIS
autogsdoc [-Archivos nombre de archivo] [-Generar HTML SI | no] [-Limpio si | NO] [-Limpiar Plantillas
si | NO] [-Ignorar dependencias si | NO] [-Hacer dependencias si | NO] [-Mostrar dependencias si | NO]
[-DirectorioEncabezado camino] [-Directorio de documentación camino] [-Declarado localización] [-Proyecto
título] [-Normas si | NO] [-DocumentAllInstanceVariables si | NO]
[-Variables de instancia de documento SI | no] [-Variables de instancia al final si | NO] [-Plantilla de constantes
nombre de archivo] [-Funciones Plantilla nombre de archivo] [-Plantilla de macros nombre de archivo] [-TypedefsPlantilla
nombre de archivo] [-Plantilla de variables nombre de archivo] [-Proyectos de sistema cadena] [-Proyectos Locales cadena]
[-Proyectos dictString] [-Verboso si | NO] [-Advertir si | NO] [-Mapa de palabras dictString] [archivos]
DESCRIPCIÓN
La herramienta autogsdoc es una utilidad de línea de comandos que ayuda a los desarrolladores a producir referencias
documentación para las API de GNUstep. También permite a los desarrolladores escribir y mantener otros
documentación en XML y convertirla a HTML. En detalle, autogsdoc:
- Extraer comentarios especiales que describen 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 de origen) en archivos XML GSDoc.
- Convierta archivos XML GSDoc, ya sea generados a partir del código fuente o escritos manualmente por
desarrolladores, en HTML.
- Construya índices basados en conjuntos de archivos XML 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 fuente correspondientes en el mismo
directorio como los encabezados (o el directorio actual, o el directorio especificado usando el
DocumentationDirectory predeterminado) y genera archivos GSDoc y HTML como salida. Para mejor
resultados este modo debe ejecutarse desde el directorio que contiene los archivos fuente. (Nota
que dado que C es un subconjunto del objetivo C, esta herramienta puede operar para documentar funciones y
otras estructuras C en fuente C simple).
Los archivos GSDoc también se pueden proporcionar directamente de forma adicional o por sí mismos, y se convertirán
a HTML. Consulte la documentación HTML de GSDoc o el gsdoc(7) página de manual para obtener información sobre el
Formato GSDoc.
Finalmente, los archivos HTML se pueden proporcionar en la línea de comandos. Referencias cruzadas a otras partes de
La documentación del código que se encuentra dentro de ellos se reescribirá en función de lo que se encuentre en el
proyecto actualmente.
FUENTE CÓDIGO MARGEN
El analizador de código fuente producirá automáticamente documentos GSDoc enumerando los métodos en
las clases que se encuentran en los archivos de origen, e incluirá texto de formato especial
comentarios de los archivos fuente.
Cualquier comentario que comience con barra y two asteriscos en lugar de la barra común y simple
asterisco, se toma como marcado GSDoc, para ser utilizado como descripción de la clase o método
siguiéndolo. Este texto de comentario se reformatea y luego se inserta en la salida.
Cuando se asocian varios comentarios con el mismo elemento, se unen con un
salto de línea ) entre cada uno si es necesario.
La herramienta se puede utilizar fácilmente para documentar programas y bibliotecas, simplemente dándole
el nombre del archivo fuente que contiene la función main () del programa - toma el
comentarios especiales de esa función y los maneja especialmente, insertándolos como un
sección al final del primer capítulo del documento (crea el primer capítulo si
necesario).
se describen en la sección Argumentos y predeterminados abajo.
EXTRA MARGEN
Hay algunos casos en los que se realiza un procesamiento adicional especial, predominantemente en el
primer comentario encontrado en el archivo de origen, del cual se pueden obtener varios fragmentos de marcado GSDoc
extraído y colocado en ubicaciones apropiadas en el documento de salida -
AutogsdocFuente:
En cualquier línea donde AutogsdocFuente: se encuentra, el resto de la línea se toma como
nombre del archivo de origen que se utilizará en lugar de suponer que cada archivo .h
procesado utiliza un archivo .m del mismo nombre. Puede suministrar varios AutogsdocFuente:
líneas donde un archivo de encabezado declara elementos que están definidos en múltiples archivos fuente.
Si un nombre de archivo es absoluto, se utiliza tal como se proporciona. Si por otro lado, es un
ruta relativa, el software busca el archivo de origen primero en relación con la ubicación
del archivo de encabezado, y si no se encuentra allí, en relación con el directorio actual en el que
autogsdoc se está ejecutando, y finalmente en relación con el directorio especificado por el
DocumentaciónDirectorio predeterminada.
Un resumen del contenido del documento ... colocado en el encabezado de la salida de GSDoc.
Una descripción del autor del código - puede repetirse para manejar el caso donde un
el documento tiene varios autores. Colocado en la cabecera de la salida GSDoc. Como ayuda para
legibilidad de la fuente, se realiza algún procesamiento adicional especial relacionado con
el autor del documento: cualquier línea del formulario 'Autor: nombre ', o por:
nombre ', o' Autor: nombre 'o' Por: nombre 'serán reconocidos y
convertido en un autor elemento, posiblemente conteniendo un correo electrónico elemento.
Colocado en la salida de GSDoc justo antes del final del cuerpo del documento - previsto
para ser utilizado en 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 está documentando. Alguna
la 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 GSDoc.
Como ayuda para la legibilidad de la fuente, se requiere algún procesamiento adicional especial.
Realizado: cualquier línea del formulario 'Texto de Copyright (C)' será reconocida y convertida
a una copia elemento.
Fecha de la revisión del documento ... colocada en el encabezado de la salida GSDoc. Si
esto se omite, la herramienta intentará construir un valor a partir de la etiqueta de fecha RCS (si
disponible).
Insertado en el documento al principio del cuerpo ... destinado a proporcionar
introducción o páginas de contenido, etc.
Título del documento ... colocado en el encabezado de la salida GSDoc. Si esto se omite
la herramienta generará un título propio (probablemente pobre), por lo que debe incluir esto
marcado manualmente.
Identificador de versión del documento ... colocado en el encabezado de la salida GSDoc. Si
esto se omite, la herramienta intentará construir un valor a partir de la etiqueta RCS Revision (si
disponible).
NB El marcado que se acaba de describir se puede utilizar dentro de la documentación de clase, categoría o protocolo
... si es así, se extrae y se envuelve alrededor del resto de la documentación de la clase
como capítulo de la clase. El resto de la documentación de la clase normalmente se inserta en el
final del capítulo, pero en su lugar puede ser sustituido en lugar de la seudo-
elemento dentro del elemento.
MÉTODO MARGEN
En los comentarios que se utilizan para proporcionar texto para la descripción de un método, el siguiente marcado es
eliminado del texto y manejado especialmente -
El método está marcado como el inicializador designado para la clase.
El método se marca como uno que las subclases deben anular (por ejemplo, un resumen
método).
El método está marcado como uno cuyas subclases deben anular.
El marcado se elimina de la descripción y se coloca después en la salida GSDoc -
de modo que el método se describa como conforme (o no conforme) a la especificación
normas
AUTOMATIZADO MARGEN
Generalmente, el texto en los comentarios se reformatea para estandarizarlo y sangrarlo bien ...
reformatear es no sea realizado en cualquier texto dentro de un elemento. Cuando el texto es
reformateado, se divide en "palabras" separadas por espacios en blanco que luego se someten a
algún procesamiento adicional ...
Ciertas constantes bien conocidas como YES, NO y nil se incluyen en ...
margen.
Los nombres de los argumentos del método dentro de las descripciones del método se incluyen entre ...
</ var> marcado.
Los nombres de los métodos (que comienzan con un más o un menos) se incluyen en ...
margen. Por ejemplo, "-init" (sin las comillas) estaría envuelto en una referencia GSDoc
elemento para apuntar al método init de la clase actual o, si solo una clase conocida
tenía un método init, se referiría al método de esa clase. Tenga en cuenta el hecho de que
el nombre del método debe estar rodeado de espacios en blanco para ser reconocido (aunque una coma,
punto y coma al final del especificador actuará como un espacio en blanco).
Especificadores de métodos que incluyen nombres de clases (que comienzan y terminan con corchetes)
están encerrados en ... margen. por ejemplo, '[NSObject-init]', creará un
referencia al método init de NSObject (ya sea la clase propiamente dicha, o cualquiera de sus
categorías), mientras que '[(NSCopying) -copyWithZone:]', crea una referencia a un método en
el protocolo NSCopying. Tenga en cuenta que no deben aparecer espacios entre los corchetes
en estos especificadores. Los nombres de los protocolos se incluyen entre corchetes en lugar de
corchetes angulares habituales, porque GSDoc es un lenguaje XML, y XML trata el ángulo
soportes especialmente.
Los nombres de funciones (que terminan con '()') distintos de 'main ()' se incluyen en ...
margen. Por ejemplo, "NSLogv ()" (sin las comillas) estaría envuelto en un GSDoc
elemento de referencia para señalar la documentación de la función NSLog. Note el hecho
que el nombre de la función debe estar rodeado de espacios en blanco (aunque una coma, punto final o
el punto y coma al final del especificador también actuará como un terminador de espacios en blanco).
ARGUMENTOS Y INCUMPLIMIENTOS
La herramienta acepta ciertos valores predeterminados del usuario (que, por supuesto, se pueden proporcionar como línea de comandos
argumentos anteponiendo '-' antes del nombre predeterminado y dando el valor después, como en
-Limpiar SÍ):
Fácil
Si este valor booleano se establece en SÍ, en lugar de generar documentación, el
La herramienta elimina todos los archivos GSDoc generados en el proyecto y todos los archivos html generados.
de ellos (así como cualquiera que se generaría 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 esa plantilla los archivos GSDoc (es decir, los especificados mediante "-ConstantsTemplate ...",
"-FunctionsTemplate ..." argumentos, etc.) no se eliminan a menos que CleanTemplates
la bandera está puesta.
Plantillas limpias
Este indicador especifica si los archivos GSDoc de plantilla deben eliminarse junto con otros
archivos cuando se especifica la opción Limpiar. El valor predeterminado es que no se eliminen
... ya que estas plantillas pueden haberse producido manualmente y solo se han insertado datos
en ellas.
Plantilla de constantes
Especifique el nombre de un documento de plantilla en el que la documentación sobre constantes
debe insertarse desde todos los archivos del proyecto. Esto es útil si las constantes en el
El código fuente se encuentra disperso en muchos archivos y es necesario agruparlos en uno.
lugar. Usted es responsable de asegurarse de que el documento modelo básico (en el que
se inserta la documentación constante individual) contiene toda la otra información que
desee, pero para su conveniencia, autogsdoc generará una plantilla simple (que puede
luego edite) por usted si el archivo no existe. La inserción se realiza de inmediato
antes de back elemento (o si no existe, inmediatamente antes del final del
cuerpo elemento) en la plantilla.
Declarado
Especifique dónde se documentarán los encabezados que se encuentran. El nombre real producido
en la documentación se forma agregando el último componente del nombre del archivo de encabezado
al valor de este predeterminado. Si no se especifica este valor predeterminado, el nombre completo del
archivo de encabezado (como se proporciona en la línea de comando), con el directorio de encabezado predeterminado
antepuesto, se utiliza. Un uso típico de esto podría ser '"-Declared Foundation"' cuando
generar documentación para la biblioteca base GNUstep. Esto daría como resultado la
documentación que dice que NSString está declarado en 'Foundation / NSString.h'
DocumentAllInstanceVariables
Esta bandera le permite generar documentación para todas las variables de instancia. Normalmente,
sólo se documentarán aquellos declarados explícitamente como "públicos" o "protegidos".
DocumentInstanceVariablesDocumentInstanceVariables
Esta bandera le permite desactivar completamente la documentación de las variables de instancia.
Normalmente, las variables de instancia declaradas explícitamente 'públicas' o 'protegidas' serán
Documentada.
Variables de instancia al final
Esta marca, si se establece, indica al generador 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 muchos
variables de instancia protegidas que sólo serán de interés secundario para
usuarios generales de la clase.
DocumentaciónDirectorio
Puede utilizarse para especificar el directorio en el que se colocará la documentación generada.
Si no se establece, la salida se coloca en el directorio actual. Este directorio también es
se utiliza como último recurso para localizar archivos de origen (no encabezados) y, lo que es más importante,
se usa como el first y único recurrir para localizar los archivos .gsdoc que se pasan en
la línea de comando. Cualquier información de ruta proporcionada para estos archivos es remoto y estan
buscado en 'DocumentationDirectory' (aunque no hayan sido
auto generado).
Archivos
Especifica el nombre de un archivo que contiene una lista de nombres de archivo como una matriz de lista de propiedades
(nombre1, nombre2, ...) formato. Si está presente, los nombres de archivo en la lista de argumentos del programa
se ignoran y los nombres de este archivo se utilizan como lista de nombres para procesar.
FuncionesPlantilla
Especifique el nombre de un documento de plantilla en el que la documentación sobre funciones
debe insertarse desde todos los archivos del proyecto. Esto es útil si la fuente de la función
El código está disperso en varios archivos y debe agruparlo en un solo lugar. Usted está
responsable de asegurar que el documento modelo básico (en el que individuo
la documentación de la función está insertada) contiene toda la otra información que desea, pero
como una conveniencia, autogsdoc generará una plantilla simple (que luego puede editar)
para usted si el archivo no existe. La inserción tiene lugar inmediatamente antes de la back
elemento (o si no existe, inmediatamente antes del final del cuerpo elemento) en
la plantilla.
Generar HTML
Puede usarse para especificar si se va a generar una salida HTML. El valor predeterminado es SÍ.
Directorio de encabezado
Puede usarse para especificar el directorio en el que se buscarán los archivos de encabezado. Cuando se suministra,
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. Archivos de encabezado especificados como absolutos
Las rutas no están influenciadas por este valor predeterminado.
Ignorar dependencias
Un valor booleano que puede usarse para especificar que el programa debe ignorar el archivo.
tiempos de modificación y regenerar archivos de todos modos. Se proporciona para su uso junto con
el sistema 'make', que se espera que gestione la comprobación de dependencias por sí mismo.
Proyectos locales
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
establecido en 'Ninguno', entonces no se hacen referencias al proyecto local, de lo contrario, el 'Local'
El directorio de documentación de GNUstep se busca de forma recursiva en busca de archivos con un '.igsdoc'
extensión, y se utiliza la información de indexación de esos archivos. El valor de esto
La 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 utilizar es un archivo en el mismo directorio donde
Se encontró el archivo igsdoc; de lo contrario, se usa 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 sea
ser incluido por este mecanismo. Si desea incluir este tipo de proyectos, debe hacerlo
usando explícitamente -Proyectos ...
Plantilla de macros
Especifique el nombre de un documento de plantilla en el que debe incluirse la documentación sobre macros.
insertarse desde todos los archivos del proyecto. Esto es útil si el código de macro está disperso
alrededor de muchos archivos, y debe agruparlos en un solo lugar. Tu eres responsable de
asegurándose de que el documento de plantilla básico (en el que la documentación de macros individuales
se inserta) contiene toda la otra información que desee, pero para su conveniencia
autogsdoc generará una plantilla simple (que luego puede editar) para usted si el
el archivo no existe. La inserción tiene lugar inmediatamente antes de la back elemento (o si
que no existe, inmediatamente antes del final de la cuerpo
elemento) en la plantilla.
HacerDependencias
Un nombre de archivo que se utilizará para generar información de dependencia para make. Esto tomará el
forma de listar todos los archivos fuente y de encabezado conocidos para el proyecto como dependencias de
el nombre del proyecto (ver 'Proyecto').
Proyectos
Puede usarse para especificar el nombre de este proyecto ... determina el nombre del índice
archivo de referencia producido como parte de la documentación para proporcionar información que permita
otros proyectos para hacer una referencia cruzada a los elementos de este proyecto.
Proyectos
Este valor se puede proporcionar como un diccionario que contiene las rutas al igsdoc
archivos de índice / referencia utilizados por proyectos externos, junto con los valores que se utilizarán para mapear
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 del proyecto es '/ usr / share / doc / proj', luego la salida html generada puede hacer referencia
la clase como en '/usr/share/doc/prj/Foo.html'. Tenga en cuenta que un diccionario puede ser
dado en la línea de comando utilizando el formato PropertyList estándar (no el XML
formato de OS X), utilizando punto y coma como separadores de línea, y encerrándolo en un solo
citas.
Mostrar Dependencias
Un valor booleano que puede usarse para especificar que el programa debe registrar qué archivos
se están regenerando debido a su dependencia de otros archivos.
Estándares
Un valor booleano que se utiliza para especificar si el programa debe insertar información sobre
cumplimiento de los estándares en la documentación. Esto solo debe usarse cuando
documentar las bibliotecas y herramientas GNUstep en sí mismas, ya que asume que el código
ser documentado es parte de GNUstep y posiblemente cumple con el estándar OpenStep
o implementa métodos compatibles con MacOS-X.
Proyectos de sistema
Este valor se utiliza para controlar la inclusión automática de proyectos externos del sistema en
el sistema de indexación para la generación de referencias cruzadas en la salida del documento final. Si
establecido en 'Ninguno', entonces no se hacen referencias al proyecto del sistema, de lo contrario, el 'Sistema'
El directorio de documentación de GNUstep se busca de forma recursiva en busca de archivos con un '.igsdoc'
extensión, y se utiliza la información de indexación de esos archivos. El valor de esto
La 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 utilizar es un archivo en el mismo directorio donde
Se encontró el archivo igsdoc; de lo contrario, se usa 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 sea
ser incluido por este mecanismo. Si desea incluir este tipo de proyectos, debe hacerlo
usando explícitamente -Proyectos ...
Plantilla Typedefs
Especifique el nombre de un documento de plantilla en el que la documentación sobre typedefs debe
insertarse desde todos los archivos del proyecto. Esto es útil si el código fuente typedef es
dispersos alrededor de muchos archivos, y debe agruparlos en un solo lugar. Usted está
responsable de asegurar que el documento modelo básico (en el que individuo
se inserta la documentación typedef) contiene toda la otra información que desea, pero como
un autogsdoc de conveniencia generará una plantilla simple (que luego puede editar) para
usted si el archivo no existe. La inserción tiene lugar inmediatamente antes de la back
elemento (o si no existe, inmediatamente antes del final del cuerpo elemento) en
la plantilla.
Up Una cadena que se utiliza para proporcionar el nombre que se utilizará en el enlace 'arriba' del GSDoc generado
documentos. Normalmente debería ser el nombre de un archivo que contiene un índice de la
contenido de un proyecto. Si esto falta o está configurado como una cadena vacía, entonces no 'up'
El enlace se proporcionará en los documentos.
Plantilla de variables
Especifique el nombre de un documento de plantilla en el que la documentación sobre variables
debe insertarse desde todos los archivos del proyecto. Esto es útil si la fuente variable
El código está disperso en varios archivos y debe agruparlo en un solo lugar. Usted está
responsable de asegurar que el documento modelo básico (en el que individuo
se inserta documentación variable) contiene toda la otra información que desea, pero
como una conveniencia, autogsdoc generará una plantilla simple (que luego puede editar)
para usted si el archivo no existe. La inserción tiene lugar inmediatamente antes de la back
elemento (o si no existe, inmediatamente antes del final del cuerpo elemento) en
la plantilla.
Verboso
Un booleano que se usa para especificar si desea que la salida de depuración / advertencia sea detallada.
producido.
Advertir
Un booleano que se usa para especificar si desea una salida de advertencia estándar (por ejemplo, informe de
métodos indocumentados) producidos.
Mapa de palabras
Este valor es un diccionario que se utiliza para asignar identificadores / palabras clave que se encuentran en los archivos de origen.
a otras palabras. Generalmente no tendrá que usar esto, pero a veces es útil
para evitar que el analizador se confunda con el uso de macros del preprocesador de C. Usted puede
redefinir efectivamente la macro a algo menos confuso. El valor que mapea el
identificador a debe ser uno de - Otro identificador, Una cadena vacía - el valor es
ignorado, dos barras ('//'): el resto de la línea se ignora. Tenga en cuenta que un diccionario
puede darse en la línea de comando utilizando el formato PropertyList estándar (no el
Formato XML de OS X), utilizando punto y coma como separadores de línea y encerrándolo en un solo
citas.
INTERDOCUMENTO ENLACE
El valor predeterminado 'Arriba' se usa para especificar el nombre de un documento que debe usarse como
enlace 'arriba' para cualquier otro documento utilizado. Este nombre no debe incluir una ruta ni una extensión.
Generalmente, el documento al que se hace referencia por defecto debe ser un documento GSDoc editado a mano
que debe tener una sección posterior que contenga un índice de proyecto. p.ej
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 1.0.3//ES"
"http://www.gnustep.org/gsdoc-1_0_3.xml">
Mi proyecto de referencia
de cierre
Mi proyecto de referencia
Utilice autogsdoc en línea utilizando los servicios de onworks.net