6

この質問は、ASDoc を使用して AS3 からドキュメントを作成することに関するものです。Flex などからこれを行っているわけではなく、コマンド ラインを使用しているだけです。すべて正常に動作し、ASDoc はエラーを返しませんが、結果のドキュメントのリンクの一部が壊れています。

具体的には、ドキュメントの他の部分 (同じクラスを含む) のプロパティまたはメソッドへのリンクがあるすべての場所で、リンクはパッケージに対応するフォルダーを 2 倍にしてしまいます。

たとえば、私がドキュメントを作成しているとしますmyPackage.MyClass。MyClassというプロパティがありMyProperty、ドキュメントのどこかに次のような行が含まれている場合:

@see #MyProperty

次に、ドキュメントが正しく解析され、「参照:」リンクが正しく作成されますが、最終的には

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

もちろん、実際のファイル システムにはmyPackageフォルダが 1 つしかありません。

ASDoc コマンドの関連部分は次のようになります。

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"

リンクのベース URL を指定する ASDoc 引数、またはそれらの行に沿った何かが欠落している可能性がありますか? これが単純なバグである場合、多くの人にとって明らかな問題ですが、Google でこの問題に関する検索結果を見つけることができないため、私の作業仮説は、Flex から ASDoc を実行しているユーザーには発生しないということです。省略しました。

助けてくれてありがとう！

TypeOneError の提案で、さまざまな種類の @see リンクを試しました。これらがうまく機能することがわかりました：

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

これらは機能しませんが：

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

少し悪いのは、すべてのナビゲーション リンクが機能するにもかかわらず、自動生成されたタイプのリンクで同じ二重パスが発生することです。たとえば、各メソッドのシグネチャが表示されている場合、メソッドがドキュメントにあるクラスを返す場合、そのリンクは壊れています。

HTML も調べたところ、問題はページのベース URL などにあるようには見えず、単にリンクの一貫性がないことがわかりました。したがって、連続した@seeリンクの列では、上記の規則に従って、 にClassName.htmlリンクするものとにリンクするものがあります。package/ClassName.htmlちなみに、これはすべて、ページがフレームで表示されているかどうかに関係なく当てはまります。

私が何かを理解した場合の詳細情報ですが、回避策のアイデアは大歓迎です。

更新:いくつかの詳細: Flex 3 に付属していたことを除いて、正確な SDK バージョンはわかりませんが、引数なしで ASDoc を実行すると、次のように報告されますAdobe ASDoc Version 3.3.0 build 4852。クラスパスディレクトリに配置されたバッチファイルから、これをすべてWindows XPで実行しています。

部分的な解決策: Flex 4 SDK の 4.0.0.7219 ベータ リリースにアップグレードすることによって (およびそこに配布されている ASDoc を使用することによって)、1 つを除くすべての問題が解決されました。これで、すべての@seeタグが期待どおりに機能します。唯一残っている問題は、ドキュメントの一部であるクラスを返すメソッドがある場合、ASDoc が単にリンクを壊してしまうことです。たとえば、署名が であるメソッドがある場合ClassA#getB():ClassB、それがドキュメントに示されている場合、テキスト「ClassB」は「packageName/ClassB.html」ではなく「packageName:ClassB.html」にリンクしています。これは単純なバグのようです。ブレ。

4

3 に答える 3

1

ASDoc はどこまでもイライラさせられます。@see に完全なパッケージ/クラス名を明示的に追加しようとしましたか。

@see myPackage.myClass#MyProperty

それが違いを生むかどうかを確認するには？

編集

あなたの調査結果に基づいていくつかのテストを実行しましたが、内部プロパティ マーカーが機能しています。すなわち

@see #_dispatcher

ページ上のそのプロパティに直接リンクします (二重のサブフォルダーはありません)。コマンドの実行方法を再考する必要があると思います。たとえば、私のコードベースは次のように設定されています。

/src
    /com
        /bkwld
            /fetch

通常、「src」内で asdoc を実行します。

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

これらすべてを Fetch.as で試したところ、すべて期待どおりに機能しました。

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

最初に FetchItem ページに移動し、2 番目に別のパッケージの Logger ページに移動し、3 番目に Fetch の保護されたメソッドにジャンプしました。

好奇心から...使用しているSDKのバージョンを教えてください。

于 2009-06-01T20:57:16.050 に答える
0

上記のケースで asdoc によって誤って生成されたパスを修正する簡単な Python スクリプトを作成しました。つまり、メソッド myMethod(v:MyClass,...) がある場合、asdoc は誤ってリンク href="../mypackage:Myclass" を生成します。スクリプトはこれを修正し、: を / に置き換えます。

私が生成しているドキュメントはかなり「フラットな」構造、つまり、多数のクラスを持つ単一のパッケージであることに注意してください。修正がより複雑なドキュメント構造で機能するかどうかはわかりません。

とにかく、スクリプトを試してみたい人がいれば、喜んでお送りします。

于 2009-06-20T12:02:20.047 に答える
0

問題はあなたのラインだと思います

-doc-sources myPackage

「.」の指定 「myPackage」の代わりに修正する必要があります（ソースパスと同じにします）

于 2009-06-01T11:01:05.227 に答える