La fijación de caminos rotos en ASDoc?

StackOverflow https://stackoverflow.com/questions/934176

  •  06-09-2019
  •  | 
  •  

Pregunta

Esta cuestión se refiere ASDoc utilizando para crear la documentación de AS3. No estoy haciendo esto desde Doble o nada, sólo la línea de comandos, y si todo funciona bien y ASDoc no devuelve ningún error, algunos de los eslabones de la documentación resultante se rompen.

Específicamente, en todos los lugares en los que hay enlaces a propiedades o métodos en otras partes de la documentación (incluyendo en la misma clase), el enlace termina la duplicación de la carpeta que corresponde al paquete.

Por ejemplo, decir que estoy documentando myPackage.MyClass. Si MyClass tiene una propiedad llamada MyProperty, y en alguna parte de mis documentos que incluyen una línea como la siguiente: 

@see #MyProperty

A continuación, los documentos se analizan correctamente y el "Ver también:" vínculo se crea correctamente, pero termina señalando 

.../output_directory/myPackage/myPackage/MyClass.html#MyProperty

donde, por supuesto, en el sistema de archivos real sólo hay una carpeta myPackage.

La parte pertinente de mi mando ASDoc se ve así: 

asdoc
 -source-path .
 -doc-sources myPackage
 -output D:\dev\repository\docs\myPackage_docs
 -external-library-path "C:\Progra~1\Adobe\flex_sdk_3\frameworks\libs\player\10\playerglobal.swc"

¿Estoy perdiendo quizá algún argumento ASDoc que especifique la URL base para los enlaces, o algo por el estilo? Si esto fue un error normal sería evidente para muchos, pero no puedo encontrar ningún resultado en Google el problema, por lo que mi hipótesis de trabajo es que no sucede con las personas que ejecutan ASDoc de Flex, tal vez debido a un cierto ajuste I 'he omitido.

Gracias por cualquier ayuda!

En la sugerencia de TypeOneError, probé diferentes tipos de enlaces @see. He descubierto que estos funcionan bien:

  • @see some.package
  • @see ClassName
  • @see ClassName#property

mientras estos no funcionan:

  • @see #property
  • @see full.package.ClassName
  • @see full.package.ClassName#property

¿Qué es un poco peor es, a pesar de todos los enlaces de navegación funcionan, el mismo camino duplicado se produce en los enlaces de tipo generados automáticamente. Por ejemplo, donde se muestra la firma de cada método, cuando el método devuelve una clase que está en la documentación, que enlace está roto.

También tenía un aspecto en el código HTML, y se encontró que el problema no parece estar con URL base de la página o algo, es sólo enlaces inconsistentes. Así, en una fila de enlaces @see consecutivos, algunos de ellos enlazar a ClassName.html y algún vínculo con package/ClassName.html, por las reglas que se muestran arriba. Todo esto, por cierto, es cierto independientemente de si las páginas se ven en marcos o no.

Más información si descifrar nada, pero las ideas para soluciones son bienvenidos.

Actualización: Algunos detalles más: no estoy seguro de mi versión exacta SDK, excepto que acompaña Flex 3, pero si me quedo sin argumentos ASDoc, informa: Adobe ASDoc Version 3.3.0 build 4852. Estoy corriendo todo esto en Windows XP, a partir de un archivo por lotes se coloca en el directorio de ruta de clases.

solución parcial: todos menos uno de mis problemas se resolvieron mediante la actualización a la versión 4.0.0.7219 beta del SDK Flex 4 (y utilizando el ASDoc distribuido en el mismo). Ahora, todos mis etiquetas @see funcionan como se esperaba. El problema único que queda es que, siempre que tengo un método que devuelve una clase que es parte de mi documentación, ASDoc simplemente destroza el enlace. Por ejemplo, si tengo un método cuya firma ClassA#getB():ClassB, a continuación, donde se muestra que en la documentación, el texto "ClassB" enlaces a "packageName: ClassB.html" en lugar de "packageName / ClassB.html". Esto parece ser un simple error. Bleh.

¿Fue útil?

Solución

ASDoc es frustrante que no tiene fin. ¿Ha tratado de forma explícita añadiendo el nombre completo del paquete / clase a la @see, es decir: 

@see myPackage.myClass#MyProperty

Para ver si eso hace la diferencia?

Editar

Me encontré con algunas pruebas en función de sus resultados y el marcador de propiedad interna está funcionando para mí. es decir.

@see #_dispatcher

vincula directamente a esa propiedad en la página (sin subcarpeta doble). Creo que tal vez necesita volver a pensar cómo se está ejecutando el comando. Por ejemplo, mi código base está configurado de esta manera: 

/src
    /com
        /bkwld
            /fetch

Me suelen correr asdoc dentro "src": 

asdoc -source-path . -doc-classes com/bkwld/fetch/Fetch

He intentado todos estos en Fetch.as y que todo funcionaba como era de esperar: 

*  @see FetchItem
*  @see com.bkwld.utils.Logger
*  @see #_dispatcher

En primer lugar me llevó a la página FetchItem, en segundo lugar me llevó a la página Logger en un paquete diferente, y la tercera saltaron a la página de los métodos protegidos de Fetch.

Sólo por curiosidad ... ¿qué versión del SDK está usando?

Otros consejos

Yo diría que el problema es su línea

-doc-fuentes myPackage

Especificación ''. allí en vez de 'myPackage' debe lograr que se fija (por lo que sea idéntica a la ruta de origen)

He escrito un simple script en Python que fija los caminos incorrectamente generadas por asdoc en el caso antes mencionado arriba. Es decir, si hay un método myMethod (v: MiClase, ...) asdoc genera incorrectamente el enlace href = "../ mypackage: Myclass" El guión solucionará el problema reemplazando el: por un /

Debería notar que los documentos estoy generando tienen una estructura muy "plana", es decir, un solo paquete con un montón de clases. No tengo idea de si el arreglo trabaja con estructuras de documentación más complejas.

De todos modos, si alguien quiere probar el guión, me alegraré de enviarlo.

Licenciado bajo: CC-BY-SA con atribución
No afiliado a StackOverflow
scroll top