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.¿Reparar caminos rotos en ASDoc?
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, supongo que estoy documentando myPackage.MyClass. Si MyClass tiene una propiedad llamada MyProperty, y en alguna parte de mis documentos incluyo una línea como esta:
@see #MyProperty
continuación, los documentos se analizan correctamente y el "Véase también:" vínculo se crea correctamente, pero termina señalando a
.../output_directory/myPackage/myPackage/MyClass.html#MyProperty
donde, por supuesto, en el sistema de archivos real sólo hay una myPackage carpeta.
La parte pertinente de mi mando ASDoc se parece a esto:
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 quizá falta algún argumento ASDoc que especifique la URL base para los enlaces, o algo por el estilo? 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!
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, 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 encontré que el problema no parece ser con la URL base de la página ni nada, solo son enlaces inconsistentes. Por lo tanto, en una fila de enlaces @see consecutivos, algunos de ellos se vinculan al ClassName.html y algunos a 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 entiendo algo, pero las ideas para soluciones son bienvenidas.
Actualizar: 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 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 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, 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 cuando 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.
Hmm, sí marcó la diferencia ... Actualizaré con los resultados. – fenomas
Agregó una prueba, FYI – typeoneerror
Muchas gracias por la prueba mate, esto suena solucionable. Estoy llamando ASDoc de manera similar a usted: guardo el archivo por lotes en mi directorio classpath, en el mismo nivel que mi paquete superior ("com" en su ejemplo). Agregaré algunos detalles de la versión a mi pregunta también. No está utilizando FlexBuilder o Eclipse para ejecutar ASDoc, ¿verdad? – fenomas