Correggere i percorsi danneggiati in ASDoc?

Question

Questa domanda riguarda l'utilizzo di ASDoc per creare documentazione da AS3. Non sto facendo questo da Flex o altro, semplicemente usando la riga di comando, e anche se tutto funziona correttamente e ASDoc non restituisce errori, alcuni dei collegamenti nella documentazione risultante sono interrotti.

In particolare, in tutti i punti in cui sono presenti collegamenti a proprietà o metodi in altre parti della documentazione (incluso nella stessa classe), il collegamento termina 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 includo una linea come questa:

@see #MyProperty 

poi i documenti vengono analizzati correttamente e la "Consulta anche:" collegamento viene correttamente creato, ma finisce di puntamento a

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

dove ovviamente, nel file system attuale v'è un solo myPackage cartella.

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" 

Perchè sono forse manca qualche argomento ASDoc che specificare l'URL di base per i collegamenti, o qualcosa del genere? Se questo fosse un errore, sarebbe evidente a molti, ma non riesco a trovare alcun risultato su Google per il problema, quindi la mia ipotesi di lavoro è che non succede alle persone che eseguono ASDoc da Flex, forse a causa di qualche impostazione 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

mentre 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. Ad esempio, dove mostra la firma di ogni metodo, quando il metodo restituisce una classe presente nella documentazione, quel collegamento è interrotto.

Ho anche dato un'occhiata all'HTML e ho scoperto che il problema non sembra essere relativo all'URL di base della pagina o altro, sono solo collegamenti incoerenti. Quindi in una fila di link consecutivi @see, alcuni di essi si collegano a ClassName.html e alcuni link a package/ClassName.html, secondo le regole mostrate sopra. Tutto questo, a proposito, è vero indipendentemente dal fatto che le pagine siano visualizzate in frame o meno.

Ulteriori informazioni se capisco qualcosa, ma le idee per soluzioni alternative sono i benvenuti.

---

Aggiornamento: 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. Sto eseguendo tutto questo su Windows XP, da un file batch inserito 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 rimanente è che, ovunque disponga di un metodo che restituisce una classe che fa parte della mia documentazione, ASDoc semplicemente altera il collegamento. Ad esempio, se ho un metodo la cui firma è ClassA#getB():ClassB, quindi dove è mostrato nei documenti, il testo "ClassB" si collega a "packageName: ClassB.html" anziché a "packageName/ClassB.html". Questo sembrerebbe essere un bug semplice. Bleh.

Answer 1

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

@see myPackage.myClass#MyProperty 

per vedere se questo fa la differenza?

Modifica

ho fatto un paio di prove, sulla base di risultati e il marcatore di proprietà interna sta lavorando per me. vale a dire

@see #_dispatcher

Link direttamente alla proprietà nella pagina (nessun doppio sottocartella). Penso che forse hai bisogno di ripensare a come stai eseguendo il comando. Per esempio, il mio codice di base è impostato nel seguente modo:

/src 
    /com 
     /bkwld 
      /fetch 

Io di solito gestita 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 

Prima mi portava alla pagina FetchItem, in secondo luogo mi portavo alla pagina Logger in un altro pacchetto, e in terzo luogo saltava la pagina ai metodi protetti di Fetch.

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

Answer 2

direi il problema è la vostra linea di

-doc-sources mypackage

Specifica '' lì invece di "myPackage" dovresti farlo riparare (quindi renderlo identico al tuo percorso sorgente)

Answer 3

Ho scritto un semplice script Python che corregge i percorsi generati erroneamente da asdoc nel caso menzionato sopra. Vale a dire, se c'è un metodo myMethod (v: MyClass, ...) asdoc genera erroneamente il link href = "../ mypackage: Myclass " Lo script risolverà questo sostituendo: by a/

Dovrei notare che i documenti che sto generando hanno una struttura piuttosto" piatta ", cioè un singolo 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 per inviarlo.

non