StackOverflow2013

Note that there are some explanatory texts on larger screens.

plurals

POFixing broken paths in ASDoc?
text
Body
copied!<p>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.</p> <p>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.</p> <p>For example, say I'm documenting <code>myPackage.MyClass</code>. If <code>MyClass</code> has a property called <code>MyProperty</code>, and somewhere in my docs I include a line like this:</p> <pre><code>@see #MyProperty </code></pre> <p>then the docs are parsed correctly and the "See also:" link is correctly created, but it winds up pointing to </p> <pre><code>.../output_directory/myPackage/myPackage/MyClass.html#MyProperty </code></pre> <p>where of course, in the actual file system there is only one <code>myPackage</code> folder.</p> <p>The relevant part of my ASDoc command looks like this:</p> <pre><code>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" </code></pre> <p>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.</p> <p>Thanks for any help!</p> <hr> <p>On the suggestion of TypeOneError, I tried different kinds of @see links. I found that these work fine:</p> <ul> <li><code>@see some.package</code></li> <li><code>@see ClassName</code></li> <li><code>@see ClassName#property</code></li> </ul> <p>while these do not work:</p> <ul> <li><code>@see #property</code></li> <li><code>@see full.package.ClassName</code></li> <li><code>@see full.package.ClassName#property</code></li> </ul> <p>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.</p> <p>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 <code>@see</code> links, some of them link to <code>ClassName.html</code> and some link to <code>package/ClassName.html</code>, by the rules shown above. All of this, by the way, is true regardless of whether the pages are viewed in frames or not.</p> <p>More info if I figure anything out, but ideas for workarounds are most welcome.</p> <hr> <p><em>Update:</em> 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: <code>Adobe ASDoc Version 3.3.0 build 4852</code>. I'm running this all on Windows XP, from a batch file placed in the classpath directory.</p> <hr> <p><strong>Partial solution:</strong> 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 <code>@see</code> 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 <code>ClassA#getB():ClassB</code>, 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.</p>

Querying!

Guidance

An individual column

Larger individual text columns get their own page to allow for proper reading.

SQuiL has stopped working due to an internal error.

If you are curious you may find further information in the browser console, which is accessible through the devtools (F12).

Reload