actionscript 3 - ¿Reparar caminos rotos en ASDoc?

actionscript-3

Question

Esta pregunta se refiere al uso de ASDoc para crear documentación de AS3. No estoy haciendo esto desde Flex ni nada, simplemente usando la línea de comando, y aunque todo funciona bien y ASDoc no devuelve ningún error, algunos de los enlaces en la documentación resultante están rotos.

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

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

@see #MyProperty

entonces los documentos se analizan correctamente y el enlace "Ver también:" se crea correctamente, pero termina apuntando hacia

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

donde, por supuesto, en el sistema de archivos real solo hay una carpeta myPackage .

La parte relevante de mi comando 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"

¿Me estoy perdiendo algún argumento de ASDoc que especifique la URL base para los enlaces, o algo así? Si esto fuera un error simple, sería evidente para muchos, pero no puedo encontrar ningún resultado en Google para el problema, por lo que mi hipótesis de trabajo es que no le sucede a las personas que ejecutan ASDoc desde Flex, tal vez debido a alguna configuración he omitido

¡Gracias por cualquier ayuda!

A sugerencia de TypeOneError, probé diferentes tipos de enlaces @see. Encontré que estos funcionan bien:

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

mientras que estos no funcionan:

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

Lo que es un poco peor es que, aunque todos los enlaces de navegación funcionan, la misma ruta duplicada se produce en los enlaces de tipo generados automáticamente. Por ejemplo, cuando muestra la firma de cada método, cuando el método devuelve una clase que está en la documentación, ese enlace se rompe.

También eché un vistazo al HTML y descubrí que el problema no parece estar en la URL base de la página ni nada, solo son enlaces incoherentes. Por lo tanto, en una fila de enlaces @see consecutivos, algunos de ellos enlazan con ClassName.html y algún enlace al package/ClassName.html , según 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 descubro algo, pero las ideas para soluciones son bienvenidas.

Actualización: algunos detalles más: no estoy seguro de mi versión exacta de SDK, excepto que vino con Flex 3, pero si ejecuto ASDoc sin argumentos, informa: Adobe ASDoc Version 3.3.0 build 4852 . Estoy ejecutando todo esto en Windows XP, desde un archivo por lotes ubicado en el directorio classpath.

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

Answer 1

Supongo que el problema es tu línea

-doc-sources myPackage

Especificando ''.'' allí en lugar de ''myPackage'' debería arreglarlo (así que hazlo idéntico a tu ruta de origen)

Answer 2

ASDoc es frustrante sin fin. ¿Has intentado agregar explícitamente el nombre completo del paquete / clase al @see, es decir:

@see myPackage.myClass#MyProperty

Para ver si eso hace la diferencia?

Editar

Ejecuté algunas pruebas basadas en tus hallazgos y el marcador de propiedades internas me funciona. es decir

@ver #_dispatcher

Enlaces directamente a esa propiedad en la página (sin doble subcarpeta). Creo que tal vez necesites replantearte cómo estás ejecutando el comando. Por ejemplo, mi código base está configurado así:

/src
/com
/bkwld
/fetch

Normalmente ejecuto asdoc dentro de "src":

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

Intenté todos estos en Fetch.as y todos funcionaron como se esperaba:

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

Primero me llevó a la página de FetchItem, en segundo lugar me llevó a la página de Logger en un paquete diferente, y en tercer lugar salté la página a los métodos protegidos de Fetch.

Solo por curiosidad ... ¿qué versión del SDK estás usando?

Answer 3

Escribí un script simple de Python que corrige las rutas incorrectamente generadas por asdoc en el caso mencionado anteriormente. A saber, si hay un método myMethod (v: MyClass, ...) asdoc genera incorrectamente el enlace href = "../ mypackage: Myclass" El script arreglará esto reemplazando el: por a /

Debería notar que los documentos que estoy generando tienen una estructura bastante "plana", es decir, un paquete único con varias clases. No tengo idea si la solución funciona con estructuras de documentación más complejas.

De todos modos, si alguien quiere probar el guión, me complacerá enviarlo.