在ASDoc中修复损坏的路径？

Question

这个问题涉及使用ASDoc从AS3创建文档.我不是从Flex或其他任何东西,只是使用命令行,虽然一切正常,ASDoc没有返回任何错误,结果文档中的一些链接被破坏.

具体而言,在文档的其他部分(包括在同一类中)中存在属性或方法链接的所有位置,链接最终会使与包对应的文件夹加倍.

例如,说我正在记录myPackage.MyClass.如果MyClass有一个名为的属性MyProperty,并且在我的文档的某个地方,我包含这样一行:

@see #MyProperty

然后正确解析文档并正确创建"See also:"链接,但它最终指向

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

当然,在实际的文件系统中只有一个myPackage文件夹.

我的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"

我是否可能缺少一些ASDoc参数,它会指定链接的基本URL,或者沿着这些行的某些内容？如果这是一个普通的错误,对许多人来说很明显,但我找不到任何谷歌搜索结果的问题,所以我的工作假设是,从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通过上面显示的规则链接到一些链接.顺便说一下,无论页面是否以框架形式查看,所有这些都是正确的.

更多信息,如果我搞清楚,但欢迎解决方法的想法.

---

更新:更多细节:我不确定我的确切SDK版本,除了它伴随Flex 3,但如果我运行没有参数的ASDoc,它会报告:Adobe ASDoc Version 3.3.0 build 4852.我在Windows XP上运行这一切,来自放置在类路径目录中的批处理文件.

---

部分解决方案:通过升级到Flex 4 SDK的4.0.0.7219测试版(并使用其中分发的ASDoc)解决了我的一个问题.现在,我的所有@see标签都按预期工作.唯一剩下的问题是,无论我有什么方法返回一个属于我的文档的类,ASDoc只会破坏链接.例如,如果我有一个签名的方法ClassA#getB():ClassB,那么在文档中显示的位置,文本"ClassB"链接到"packageName:ClassB.html"而不是"packageName/ClassB.html".这似乎是一个简单的错误.的Bleh.

Answer 1

ASDoc 令人沮丧至极。您是否尝试过将完整的包/类名称显式添加到@see，即：

@see myPackage.myClass#MyProperty

看看这是否有什么不同？

编辑

我根据您的发现进行了一些测试，内部属性标记对我有用。IE

@参见#_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 页面，其次将我带到不同包中的 Logger 页面，第三次将页面跳转到 Fetch 的受保护方法。

只是出于好奇...您使用的 sdk 版本是什么？