Fixation des chemins brisés dans ASDoc?

Question

Cette question concerne l'aide ASDoc pour créer la documentation de AS3. Je ne fais pas ça de Flex ou quoi que ce soit, juste en utilisant la ligne de commande, et si tout fonctionne bien et ASDoc ne renvoie pas d'erreurs, certains des liens dans la documentation résultant sont rompus.

Plus précisément, dans tous les endroits où il y a des liens vers des propriétés ou des méthodes dans d'autres parties de la documentation (y compris dans la même classe), le lien serpente jusqu'à doubler le dossier correspondant au paquet.

Par exemple, dire que je suis la documentation myPackage.MyClass. Si MyClass possède une propriété appelée MyProperty, et quelque part dans mes documents, je comprend une ligne comme ceci:

@see #MyProperty

alors les documents sont correctement analysés et « Voir aussi: » lien est créé correctement, mais il enroule en pointant vers

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

où bien sûr, dans le système de fichiers réel il n'y a qu'un seul dossier myPackage.

La partie pertinente de ma commande ASDoc ressemble à ceci:

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"

Suis-je manque peut-être un argument ASDoc qui préciserait l'URL de base pour les liens, ou quelque chose dans ce sens? Si cela était un bug simple, il serait évident pour beaucoup, mais je ne peux pas trouver de résultats Google pour le problème, donc mon hypothèse de travail est qu'il ne se produit pas aux personnes en cours d'exécution ASDoc de Flex, peut-être à cause d'un arrangement que je « ai omis.

Merci pour toute aide!

---

Sur la suggestion de TypeOneError, j'ai essayé différents types de liens @see. J'ai trouvé que ces fonctionnent très bien:

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

alors que ceux-ci ne fonctionnent pas:

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

Qu'est-ce qu'un peu pire est, bien que tous les liens de navigation fonctionnent, le même chemin double se produit dans les liens de type générés automatiquement. Par exemple, où il montre la signature de chaque méthode, lorsque la méthode retourne une classe qui est dans la documentation, ce lien est rompu.

J'ai aussi eu un coup d'oeil au HTML, et a constaté que le problème ne semble pas être avec l'URL de base ou quoi que ce soit de la page, il est tout simplement des liens incohérents. Ainsi, dans une rangée de liens @see consécutifs, certains d'entre eux lien à ClassName.html et un lien vers package/ClassName.html, les règles ci-dessus. Tout cela, en passant, est vrai, que les pages sont vues dans des cadres ou non.

Plus d'infos si je figure quoi que ce soit, mais des idées pour des solutions de contournement sont les bienvenus.

---

Mise à jour: Quelques plus de détails: Je ne suis pas sûr de ma version exacte du SDK, sauf qu'il a accompagné Flex 3, mais si je lance ASDoc sans arguments, il rapporte: Adobe ASDoc Version 3.3.0 build 4852. Je suis en tout cela sous Windows XP, à partir d'un fichier batch placé dans le répertoire classpath.

---

Solution partielle: tous sauf un de mes problèmes ont été résolus par la mise à niveau à la version bêta 4.0.0.7219 du SDK Flex 4 (et en utilisant le ASDoc distribué dans celui-ci). Maintenant, mes balises @see fonctionnent comme prévu. Le seul problème restant est que, partout où j'ai une méthode qui retourne une classe qui fait partie de ma documentation, ASDoc Mangles simplement sur le lien. Par exemple, si j'ai une méthode dont la signature est ClassA#getB():ClassB, alors où cela est démontré dans les documents, le texte « ClassB » liens vers « packageName: ClassB.html » au lieu de « packageName / ClassB.html ». Cela semble être un bug simple. Bleh.

Answer 1

ASDoc est frustrant sans fin. Avez-vous essayé d'ajouter explicitement le package complet / nom de classe à la @see, i.e.:

@see myPackage.myClass#MyProperty

Pour voir si cela fait une différence?

Modifier

J'ai couru quelques tests en fonction de vos résultats et le marqueur de propriété interne travaille pour moi. i.e..

@see #_dispatcher

Liens directement à cette propriété sur la page (pas de double sous-dossier). Je pense que peut-être vous avez besoin de repenser la façon dont vous utilisez la commande. Par exemple, mon code de base est configuré ainsi:

/src
    /com
        /bkwld
            /fetch

Je dirige généralement asdoc l'intérieur "src":

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

J'ai essayé tout cela dans Fetch.as et ils ont tous travaillé comme prévu:

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

Tout d'abord m'a emmené à la page FetchItem, deuxième m'a emmené à la page de l'enregistreur dans un package différent, et le troisième a sauté la page aux méthodes protégées de Fetch.

Juste par curiosité ... quelle version du sdk utilisez-vous?

Answer 2

Je suppose que le problème est votre ligne

-doc-sources myPackage

Définition. ' là, au lieu de « myPackage » devrait le faire réparer (donc la rendre identique à votre chemin source)

Answer 3

J'ai écrit un simple script Python qui fixe les chemins générés de façon incorrecte à asdoc dans le cas mentionné ci-dessus. A savoir, s'il existe une méthode myMethod (v: MyClass, ...) asdoc génère de façon incorrecte le link href = "../ mypackage: Myclass" Le script va corriger ce remplaçant le: par un /

Je remarque que la structure docs je générer ont une assez « plat », c'est un seul paquet avec un tas de classes. Je ne sais pas si le correctif fonctionne avec des structures de documentation plus complexes.

Quoi qu'il en soit, si quelqu'un veut essayer le script, je serai heureux de l'envoyer.