Fissaggio sentieri interrotti a ASDoc?

Question

Questa domanda riguarda utilizzando ASDoc per creare documentazione AS3. Non sto facendo questo da Flex o altro, solo dalla riga di comando, e se tutto funziona bene e ASDoc non restituisce errori, alcuni dei collegamenti nella documentazione risultante sono rotti.

In particolare, in tutti i luoghi dove ci sono collegamenti a proprietà o metodi in altre parti della documentazione (compresi nella stessa classe), il collegamento finisce raddoppiando la cartella corrispondente al pacchetto.

Ad esempio, dire che sto documentando myPackage.MyClass. Se MyClass ha una proprietà chiamata MyProperty, e da qualche parte nei miei documenti mi includono una riga come questa:

@see #MyProperty

allora i documenti vengono analizzati correttamente e il "Vedere anche:" collegamento viene correttamente creato, ma venti fino indicando

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

dove, naturalmente, nel file system attuale non v'è una sola cartella myPackage.

La parte rilevante del mio comando ASDoc assomiglia a questo:

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"

Mi sto forse manca qualche argomento ASDoc che specificare l'URL di base per i collegamenti, o qualcosa del genere? Se questo fosse un bug semplice sarebbe evidente a molti, ma non riesco a trovare alcun risultato di Google per il problema, quindi la mia ipotesi di lavoro è che non accade a persone che corrono ASDoc da Flex, forse a causa di una certa regolazione I 'Ho omesso.

Grazie per qualsiasi aiuto!

---

Su suggerimento di TypeOneError, ho provato diversi tipi di collegamenti @see. Ho scoperto che questi funzionano bene:

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

Anche se questi non funzionano:

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

Che cosa è un po 'peggio è, anche se tutti i link di navigazione funzionano, lo stesso percorso raddoppiato avviene nei collegamenti di tipo generate automaticamente. Per esempio, dove si vede la firma di ciascun metodo, quando il metodo restituisce una classe che è nella documentazione, tale collegamento è rotto.

Ho anche avuto uno sguardo al codice HTML, e ha scoperto che il problema non sembra essere con URL di base della pagina o niente, è solo link incoerenti. Quindi, in una fila di maglie @see consecutivi, alcuni di loro collegamento a ClassName.html e qualche legame package/ClassName.html, dalle regole sopra indicati. Tutto questo, tra l'altro, è vero indipendentemente dal fatto che le pagine vengono visualizzate in frame o meno.

Più informazioni se ho dato nulla, ma le idee per soluzioni alternative sono i benvenuti.

---

Aggiornamento: A qualche dettaglio in più: io non sono sicuro della mia versione esatta SDK, tranne che accompagnava Flex 3, ma se corro ASDoc senza argomenti, esso segnala: Adobe ASDoc Version 3.3.0 build 4852. Io corro questo tutto su Windows XP, da un file batch collocato nella directory classpath.

---

Soluzione parziale: tutti, ma uno dei miei problemi sono stati risolti con l'aggiornamento alla versione 4.0.0.7219 beta del SDK di Flex 4 (e utilizzando l'ASDoc ivi distribuito). Ora, tutti i miei tag @see funzionano come previsto. L'unico problema e 'che, ovunque io ho un metodo che restituisce una classe che è parte della mia documentazione, ASDoc Mangles semplicemente il link. Per esempio, se ho un metodo la cui firma è ClassA#getB():ClassB, allora dove che viene mostrato nella documentazione, il testo "ClassB" link a "packageName: ClassB.html" invece di "packageName / ClassB.html". Questo sembrerebbe essere un semplice bug. Bleh.

Answer 1

ASDoc è frustrante a non finire. Hai provato in modo esplicito l'aggiunta del nome del pacchetto completo / classe al @see, cioè:

@see myPackage.myClass#MyProperty

Per vedere se questo fa la differenza?

Modifica

Ho eseguito alcuni test in base ai vostri risultati e il marcatore di proprietà interna sta lavorando per me. cioè.

@see #_dispatcher

Si collega direttamente a quella proprietà nella pagina (nessun doppio sottocartella). Penso che forse è necessario ripensare come si sta eseguendo il comando. Per esempio, il mio codice di base è impostato nel seguente modo:

/src
    /com
        /bkwld
            /fetch

Io di solito corro ASDoc dentro "src":

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

Ho provato tutti questi in Fetch.as e tutti hanno lavorato come previsto:

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

Per prima cosa mi ha portato alla pagina FetchItem, secondo mi ha portato alla pagina Logger in un pacchetto differente, e la terza saltato la pagina ai metodi protetti di Fetch.

Solo per curiosità ... quale versione del SDK stai usando?

Answer 2

Direi che il problema è la vostra linea

-doc-sources myPackage

Specifica '' lì, invece di 'myPackage' dovrebbe farlo fisso (quindi renderlo identico al percorso di origine)

Answer 3

Ho scritto un semplice script Python che consente di risolvere i percorsi in modo non corretto generati dal ASDoc nel caso di cui sopra menzionato. Vale a dire, se v'è un metodo myMethod (v: MyClass, ...) ASDoc genera in modo errato il link href = "../ mypackage: Myclass" Lo script risolvere questo problema sostituendo il: da un /

Vorrei notare che i documenti che sto generando hanno una struttura abbastanza "piatta", vale a dire un unico pacchetto con un gruppo di classi. Non ho idea se la correzione funziona con più strutture di documentazione complesse.

In ogni caso, se qualcuno vuole provare lo script, sarò felice di inviarlo.