6

这个问题涉及使用 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 上从放置在类路径目录中的批处理文件中运行这一切。

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

4

3 回答 3

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 的受保护方法。

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

于 2009-06-01T20:57:16.050 回答
0

我猜问题是你的线

-doc-sources myPackage

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

于 2009-06-01T11:01:05.227 回答
0

我编写了一个简单的 Python 脚本，修复了上述情况下 asdoc 错误生成的路径。即，如果有一个方法 myMethod(v:MyClass,...) asdoc 错误地生成链接 href="../mypackage:Myclass" 脚本将修复此问题，将 : 替换为 /

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

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

于 2009-06-20T12:02:20.047 回答