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而没有参数，它会报告：{{1} }。我在Windows XP上运行这一切，来自放置在类路径目录中的批处理文件。

部分解决方案：通过升级到Flex 4 SDK的4.0.0.7219测试版（并使用其中分发的ASDoc）解决了我的一个问题。现在，我的所有Adobe ASDoc Version 3.3.0 build 4852代码都按预期工作。唯一剩下的问题是，无论我有什么方法返回一个属于我的文档的类，ASDoc只会破坏链接。例如，如果我的签名为@see的方法，那么在文档中显示的位置，文本“ClassB”链接到“packageName：ClassB.html”而不是“packageName / ClassB.html”。这似乎是一个简单的错误。的Bleh。

Answer 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页面，第二次带我到另一个包中的Logger页面，第三次将页面跳到了Fetch的受保护方法。

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

Answer 2

我猜问题就在于你的行

-doc-sources myPackage

指定'。'而不是'myPackage'应该修复它（所以使它与你的源路径相同）

Answer 3

我编写了一个简单的Python脚本，修复了上面提到的情况下asdoc错误生成的路径。也就是说，如果有方法myMethod（v：MyClass，...） asdoc错误地生成链接href =“../ mypackage：Myclass” 该脚本将修复此替换：by /

我应该注意到我生成的文档有一个非常“扁平”的结构，就是一个包含一堆类的包。我不知道修复程序是否适用于更复杂的文档结构。

无论如何，如果有人想尝试这个剧本，我很乐意发送它。

在ASDoc中修复损坏的路径？

3 个答案: