ASDoc command fails on Windows

[hydroper]

Problem Description

AIR SDK version: 50.2.3 Environment: Windows

The aasdoc command results in failure for my non Flex library. I am running this simple command:

aasdoc --doc-sources+=src -o=asdoc/html

The issue I am having:

1. If I use a newer JDK, it fails due to a deprecated option; I then switched to JDK 8.
2. After switching to JDK 8 and running aasdoc again, I got

C:\Users\Mathe\UnsyncDocuments\AS3Projects\agera>java -Dsun.io.useCanonCaches=false -Xms32m -Xmx512m -Dflexcompiler="C:\airsdk\sdk\AIRSDK_50.2.3\bin\.." -Dflexlib="C:\airsdk\sdk\AIRSDK_50.2.3/frameworks" -Dflex.compiler.theme= -Xbootclasspath/p:"C:\airsdk\sdk\AIRSDK_50.2.3/asdoc/xalan.jar" -classpath "C:\airsdk\sdk\AIRSDK_50.2.3/lib/legacy/asdoc.jar" flex2.tools.ASDoc -compiler.fonts.local-fonts-snapshot= /build
Adobe ASDoc
Version 4.6.0 build 23201
Copyright (c) 2004-2011 Adobe Systems, Inc. All rights reserved.

Error: no default arguments are expected

3. After editing the asdoc.bat inside the SDK and running again, I got (oopsie, this edit was non sense!):

command line: Error: unable to open '/build'

4. After removing -compiler.fonts.local-fonts-snapshot= option, I got:

defaults: Error: unable to open 'C:\airsdk\sdk\AIRSDK_50.2.3/frameworks/localFonts.ser'

Steps to Reproduce

1. Create an empty project directory
2. Create a src directory at the project with any ActionScript sources
3. Create a asdoc/build.cmd script with the following contents:

@echo off
aasdoc --doc-sources+=src -o=asdoc/html

4. Run asdoc/build at the terminal.

[hydroper]

I have tried JDK 11 and got the same deprecation error:

C:\Users\Mathe\UnsyncDocuments\AS3Projects\agera>java -Dsun.io.useCanonCaches=false -Xms32m -Xmx512m -Dflexcompiler="C:\airsdk\sdk\AIRSDK_50.2.3\bin\.." -Dflexlib="C:\airsdk\sdk\AIRSDK_50.2.3/frameworks" -Dflex.compiler.theme= -Xbootclasspath/p:"C:\airsdk\sdk\AIRSDK_50.2.3/asdoc/xalan.jar" -classpath "C:\airsdk\sdk\AIRSDK_50.2.3/lib/legacy/asdoc.jar" flex2.tools.ASDoc -compiler.fonts.local-fonts-snapshot= /build
-Xbootclasspath/p is no longer a supported option.
Error: Could not create the Java Virtual Machine.
Error: A fatal exception has occurred. Program will exit.

[ajwfrost]

Hi

For JDK11, #1910 refers to the deprecation error - it's actually the "bootclasspath" part that needs to be removed, not the font part. So the asdoc.bat file should read:

java -Dsun.io.useCanonCaches=false -Xms32m -Xmx512m -Dflexcompiler="%FALCON_HOME%" -Dflexlib="%FLEX_HOME%/frameworks" -Dflex.compiler.theme= -classpath "%FLEX_HOME%/lib/legacy/asdoc.jar" flex2.tools.ASDoc -compiler.fonts.local-fonts-snapshot= %*

But then with that line in the batch file, it should work fine for both JDK1.8 and JDK11, I've just checked it here and it seems to work. Your command-line output for the Java 8 test with no default arguments are expected seemed like the arguments to asdoc were /build which then may be why you also see an error Unable to open /build?

Are you able to take out the incorrect part of the line - -Xbootclasspath/p:"%FLEX_HOME%/asdoc/xalan.jar" - and try again please?

thanks

[hydroper]

Your command-line output for the Java 8 test with no default arguments are expected seemed like the arguments to asdoc were /build which then may be why you also see an error Unable to open /build

It looks like there is some Batch gotcha here: if I type asdoc/build to run the build.cmd, it passes /build; if I type asdoc\build, it doesn't pass /build!

After removing the deprecated option you said and typing asdoc\build to run my command, it worked.

Of course, it looks like ASDoc is using a previous version of the Flex compiler, so I am getting an error with the null-coalescing operator...

[ajwfrost]

I'd never really looked into asdoc, but you're right about it using the older Flex compiler .. it's in the "legacy" part of the AIR SDK, and looks like it's built as part of the Flex SDK. https://github.com/apache/flex-sdk/blob/develop/modules/compiler/src/java/flex2/tools/ASDoc.java

I had wondered why it even needs to have a successful compilation in order to document the code. Wondering now whether there's a way of changing this .. e.g. see this snippet from AsDocAPI.java:

                // we call compileSwc (and use CompcPreLink, both of which should probably be renamed) to "compile" ASDoc.
                // everything runs through the normal compilation route, but we discard all of the output other than
                // what ASDocExtension creates
                CompilerAPI.compile(fileSpec, sourceList, classes.values(), sourcePath, resources, bundlePath, swcContext,
                            mappings, configuration, compilers, new CompcPreLink(null, null, true),
                            licenseMap, new ArrayList<Source>());

Maybe there's a way of catching any issues but still continuing to use the "configuration" output which seems to be the documentation (in XML format)...

[hydroper]

I'd never really looked into asdoc, but you're right about it using the older Flex compiler .. it's in the "legacy" part of the AIR SDK, and looks like it's built as part of the Flex SDK.

That explains why I had some issues with the flash_proxy namespace too...

[hydroper]

@ajwfrost I've noticed you didn't remove the -Xbootclasspath/p option yet from asdoc.bat. Can you remove it?

Nevermind, I saw the preview now

[hydroper]

-Xbootclasspath/p was not removed from Flex SDK overlay.

[ajwfrost]

Hi @hydroper -> we had removed it in our 50.2 and 51.0 branches from that asdoc.bat file, so are no longer providing a batch file with the invalid Xbootclasspath option.

The Flex SDK itself still appears to contain this though, I just looked in "apache-flex-sdk-4.16.1-bin.zip" and I have this file in the 'bin' folder with the same option still. In our overlay zips, the only things that we put into 'bin' are ADL/ADT (and new utility apps, swfcompress/swfencrypt).

I doubt the Apache Flex team would do a revised update of the release though, so I suspect you may have to manually remove that argument if you're using Flex.

thanks