Fixieren gebrochener Pfade in ASDoc?

StackOverflow https://stackoverflow.com/questions/934176

  •  06-09-2019
  •  | 
  •  

Frage

Dies betrifft Frage ASDoc mit Dokumentation von AS3 zu erstellen. Ich bin nicht die von Flex oder etwas zu tun, nur über die Befehlszeile, und wenn alles funktioniert und ASDoc Rückkehr keine Fehler, einige der Links in der resultierenden Dokumentation sind gebrochen.

Im Einzelnen in allen Orten, wo es Links zu Eigenschaften oder Methoden in anderen Teilen der Dokumentation sind (in der gleichen Klasse einschließlich), windet sich der Link auf den Ordner mit dem Paket entsprechenden verdoppeln.

Zum Beispiel, sagen, ich bin zu dokumentieren myPackage.MyClass. Wenn MyClass eine Eigenschaft namens MyProperty, und irgendwo in meiner docs schließe ich eine Zeile wie diese: 

@see #MyProperty

dann werden die Dokumente korrekt analysiert und die „Siehe auch:“ Link korrekt erstellt wird, aber es windet sich zeigt auf 

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

Dabei steht natürlich in der aktuellen Dateisystem nur ein myPackage Ordner ist.

Der relevante Teil meiner ASDoc Befehl sieht wie folgt aus: 

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"

Fehle ich vielleicht etwas ASDoc Argument, dass die Basis-URL für Links oder etwas in diese Richtung geben würde? Wenn dies ein einfacher Fehler ist, würde es zu viele offensichtlich sein, aber ich kann keine Google-Ergebnisse für das Problem finden, so dass meine Arbeitshypothese ist, dass es nicht zu den Menschen geschieht ASDoc von Flex laufen, vielleicht wegen einer Einstellung I ‚weggelassen habe.

Vielen Dank für jede Hilfe!

Auf Vorschlag von TypeOneError hat ich versucht, verschiedene Arten von @see Links. Ich fand, dass diese funktionieren:

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

, während diese nicht funktionieren:

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

Was ist ein bisschen schlimmer ist, obwohl alle Navigations-Links arbeiten, die gleiche verdoppelt Pfad automatisch generierte Typ Links erfolgt in. Zum Beispiel, wenn es jedes Verfahren Unterschrift zeigt, wenn die Methode eine Klasse zurückgibt, die in der Dokumentation ist, ist, dass Link gebrochen.

Ich hatte auch einen Blick auf der HTML, und festgestellt, dass das Problem scheint nicht mit der Seite des Basis-URL oder etwas zu sein, es ist nur inkonsistente Links. So in einer Reihe von aufeinanderfolgenden @see Links, link einige von ihnen ClassName.html und einigen Links zu package/ClassName.html, durch die Regeln oben gezeigt. Alles dies, nebenbei gesagt, wahr ist, unabhängig davon, ob die Seiten in Frames angezeigt werden oder nicht.

Weitere Informationen, wenn ich meine, alles, aber Ideen für Abhilfen sind willkommen.

Update: Noch ein paar Details: Ich bin meiner genauen SDK-Version nicht sicher, außer dass es Flex begleitet 3, aber wenn ich ASDoc ohne Argumente laufen, es berichtet: Adobe ASDoc Version 3.3.0 build 4852. Ich bin das alles auf Windows XP, aus einer Batch-Datei im Classpath-Verzeichnis platziert ausgeführt wird.

Teillösung: mit einer Ausnahme alle meine Probleme durch ein Upgrade auf die 4.0.0.7219 Beta-Version des Flex 4 SDK aufgelöst wurden (und unter Verwendung des ASDoc darin verteilt). Nun sind alle meine @see Tags funktionieren wie erwartet. Die einzige verbleibende Problem ist, dass, wo immer ich eine Methode, die eine Klasse zurückgibt, die Teil meiner Dokumentation ist, ASDoc einfach den Link verstümmelt. Zum Beispiel, wenn ich eine Methode, deren Signatur ClassA#getB():ClassB, wo dann, dass in der Dokumentation gezeigt wird, wird der Text „ClassB“ Links „package: ClassB.html“ statt „package / ClassB.html“. Dies scheint ein einfacher Fehler zu sein. Bleh.

War es hilfreich?

Lösung

ASDoc ist kein Ende frustrierend. ausdrücklich Haben Sie versucht, die volle Paket / Klassennamen den @see hinzufügen, das heißt: 

@see myPackage.myClass#MyProperty

Um zu sehen, ob das einen Unterschied macht?

Bearbeiten

lief ich ein paar Tests auf der Grundlage Ihrer Erkenntnisse und die interne Eigenschaft Marker für mich arbeitet. d.

@see #_dispatcher

Links direkt zu diesem Objekt auf der Seite (kein Doppel Unterordner). Ich denke, vielleicht müssen Sie überdenken, wie Sie den Befehl ausführen. Zum Beispiel meiner Code-Basis eingerichtet ist, so: 

/src
    /com
        /bkwld
            /fetch

ich in der Regel laufen ASDoc innen "src": 

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

Ich habe versucht, alle diese in Fetch.as und sie alle arbeiteten wie erwartet: 

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

nahm mich zum ersten Mal auf die FetchItem Seite, nahm mich Sekunde auf die Logger-Seite in einem anderen Paket und das dritte die Seite zu den geschützten Methoden der Fetch. Aufgesprungen

Nur aus Neugier ... welche Version des SDK verwenden Sie?

Andere Tipps

Ich würde vermuten, das Problem ist, Ihre Linie

-doc-Quellen myPackage

Die Angabe '' dort statt ‚myPackage‘ sollte es (so macht es identisch mit Ihrem Source-Pfad)

get fixiert

Ich habe einen einfachen Python-Skript geschrieben, die die Pfade falsch generierten durch ASDoc im Fall behebt erwähnt oben erwähnt. Das heißt, wenn es eine Methode myMethod (v: MyClass, ...) ASDoc generiert falsch den Link href = "../ mypackage: Myclass" Das Skript wird dieses Problem behebt das Ersetzen: durch a /

soll ich feststellen, dass die docs ich zu erzeugen bin eine ziemlich „flache“ Struktur hat, das heißt, ein einzelnes Paket mit einem Bündel von Klassen. Ich habe keine Ahnung, ob das Update mit komplexeren Strukturen Dokumentation funktioniert.

Wie auch immer, wenn jemand will, um das Skript versuchen, werde ich mich freuen, sie zu senden.

Lizenziert unter: CC-BY-SA mit Zuschreibung
Nicht verbunden mit StackOverflow
scroll top