Fixing broken paths in ASDoc?

Question

This question concerns using ASDoc to create documentation from AS3. I'm not doing this from Flex or anything, just using the command line, and though everything works fine and ASDoc doesn't return any errors, some of the links in the resulting documentation are broken.

Specifically, in all the places where there are links to properties or methods in other parts of the documentation (including in the same class), the link winds up doubling the folder corresponding to the package.

For example, say I'm documenting myPackage.MyClass. If MyClass has a property called MyProperty, and somewhere in my docs I include a line like this:

@see #MyProperty

then the docs are parsed correctly and the "See also:" link is correctly created, but it winds up pointing to

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

where of course, in the actual file system there is only one myPackage folder.

The relevant part of my ASDoc command looks like this:

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"

Am I perhaps missing some ASDoc argument that would specify the base URL for links, or something along those lines? If this was a plain bug it would be apparent to many, but I can't find any google results for the problem, so my working hypothesis is that it doesn't happen to people running ASDoc from Flex, perhaps because of some setting I've omitted.

Thanks for any help!

---

On the suggestion of TypeOneError, I tried different kinds of @see links. I found that these work fine:

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

while these do not work:

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

What's a bit worse is, although all the navigational links work, the same doubled path occurs in automatically generated type links. For example, where it shows each method's signature, when the method returns a class that's in the documentation, that link is broken.

I also had a look at the HTML, and found that the problem doesn't appear to be with the page's base URL or anything, it's just inconsistent links. So in a row of consecutive @see links, some of them link to ClassName.html and some link to package/ClassName.html, by the rules shown above. All of this, by the way, is true regardless of whether the pages are viewed in frames or not.

More info if I figure anything out, but ideas for workarounds are most welcome.

---

Update: A few more details: I'm not sure of my exact SDK version, except that it accompanied Flex 3, but if I run ASDoc without arguments, it reports: Adobe ASDoc Version 3.3.0 build 4852. I'm running this all on Windows XP, from a batch file placed in the classpath directory.

---

Partial solution: all but one of my issues were resolved by upgrading to the 4.0.0.7219 beta release of the Flex 4 SDK (and using the ASDoc distributed therein). Now, all my @see tags work as expected. The only remaining problem is that, wherever I have a method that returns a class that is part of my documentation, ASDoc simply mangles the link. For example, if I have a method whose signature is ClassA#getB():ClassB, then where that is shown in the docs, the text "ClassB" links to "packageName:ClassB.html" instead of "packageName/ClassB.html". This would appear to be a simple bug. Bleh.

Answer 1

ASDoc is frustrating to no end. Have you tried explicitly adding the full package/class name to the @see, i.e:

@see myPackage.myClass#MyProperty

To see if that makes a difference?

Edit

I ran a few tests based on your findings and the internal property marker is working for me. i.e.

@see #_dispatcher

Links directly to that property on the page (no double sub-folder). I think maybe you need to rethink how you're running the command. For instance, my codebase is set up thusly:

/src
    /com
        /bkwld
            /fetch

I typically run asdoc inside "src":

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

I tried all of these in Fetch.as and they all worked as expected:

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

First took me to the FetchItem page, second took me to the Logger page in a different package, and third jumped up the page to the protected methods of Fetch.

Just out of curiosity...what version of the sdk are you using?