ASDoc Generation either as HTML, or as XML to insert into SWC

[piepie62]

When I'm building a library, I often want to include its ASDoc information in the built SWC. There is currently no way to do that, to my knowledge. I took a peek at the code that might be required for that and honestly can't imagine how I would accomplish this.
The main way I could see this being done is by adding a setting to the asconfig JSON when the type is "lib" that would generate and include the ASDoc, but I could also see the merit of a separate task for it (that could be used with any asconfig), in case the user wants to build and release, for example, the HTML that comes out of the tool. I'm making this an issue rather than a PR because I don't know the best way to implement either; if given an idea, I'm happy to work on it myself. My main guess for how to implement it would be to simply change the compiler path in ASConfigC, but I'd like to make sure that that's what you would do and/or accept first.

[joshtynjala]

I don't think that I want to add asdoc support to asconfigc when building a SWC at this time. I might consider it if someone made a good, mostly-complete proposal, but I don't intend to spend time planning it out myself.

For reference, if anyone finds this on Google and wants to add asdoc data to a SWC file manually, here's how I do it for my projects:

1. Add the following command line options when running asdoc: -keep-xml=true -skip-xsl=true. Rather than generating HTML files, this will create a directory named tempdita with some XML files instead.

2. My AS3 libraries are usually built with Ant. This is how I add the contents of tempdita to the SWC with Ant:

<zip destfile="path/to/file.swc" update="true">
	<zipfileset dir="path/to/tempdita" prefix="docs">
		<include name="*.*"/>
		<exclude name="ASDoc_Config.xml" />
		<exclude name="overviews.xml" />
	</zipfileset>
</zip>

A SWC is basically just a fancy ZIP file. So this basically copies everything in tempdita except ASDoc_Config.xml and overviews.xml into a docs folder at the root of the SWC/ZIP. vscode-as3mxml, Moonshine IDE, and Flash Builder should all recognize that the SWC contains asdoc data and display it in context, but I'm not sure about other editors/IDEs for AS3.

If you're not using Ant, any zip utility should be able to insert the files.

[piepie62]

The main reason I'd want to add it to asconfigc is for the asdoc arguments to be automatically generated to match the compilation ones, but I can totally see that being fairly low priority. Without that I'd just have a brittle list of arguments in a task that don't automatically change if I change my asdoc to reflect project changes. Might have to experiment a bit to make it work well.

[joshtynjala]

If I were to add support for asdoc to asconfigc, I would probably add a new asdocOptions section to asconfig.json. This section wouldn't include all compiler options, but only the ones that are specific to asdoc (like doc-sources). When running asdoc, it would combine the compilerOptions and asdocOptions together. Possibly skipping any specific compilerOptions if they are not supported by asdoc.

[piepie62]

That seems reasonable. I unfortunately just lost access to my main dev device, but when I get a chance I'll probably start my experiments with that as a base

[piepie62]

I have built a working implementation of ASDoc generation and inclusion for at least the Flex and AIR SDKs. I can't currently figure out how to obtain a working Royale SDK to test with but I assume it wouldn't be all that different to add/change from what I currently have. I can make a PR, but I currently have it based on my additional tokens PR since my project uses it and it would change some of this as well. Would you like me to pull out those changes to make this ASDoc PR or should I just PR as-is?

[joshtynjala]

Separate PRs for different features, please.