actionscript-3 - 修复 ASDoc 中的损坏路径？

Question

这个问题涉及使用 ASDoc 从 AS3 创建文档。我不是从 Flex 或其他任何东西执行此操作，只是使用命令行，尽管一切正常且 ASDoc 不返回任何错误，但生成的文档中的某些链接已损坏。

具体来说，在文档的其他部分(包括在同一类中)中存在指向属性或方法的链接的所有地方，该链接最终将与包对应的文件夹加倍。

例如，假设我正在记录 myPackage.MyClass .如 MyClass有一个名为 MyProperty 的属性，在我的文档中的某个地方，我包含了这样的一行:

@see #MyProperty

然后正确解析文档并正确创建“另请参阅:”链接，但它最终指向

.../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 上从放在 classpath 目录中的批处理文件中运行这一切。

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

Answer 1

ASDoc 令人沮丧无止境。您是否尝试过将完整的包/类名显式添加到@see，即:

@see myPackage.myClass#MyProperty

看看这是否有区别？

编辑

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

@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 页面，第二次带我到不同包中的 Logger 页面，第三次将页面跳转到 Fetch 的 protected 方法。

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