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.