Init asconfig and run asdoc

[hydroper]

apm init

APM should be able to initialize a project with an asconfig.json file together with .as sources. You can create either an app or library through one of the commands:

• apm init asconfig app
• apm init asconfig lib

Description:

• apm init asconfig app generates...
  • asconfig.json (replace com.qux.foo by the given id)
  • libs/.gitignore (empty .gitignore file)
  • src/Main.as
  • .gitignore
  • Other files for the APM project

.gitignore

# basically ignores SWF and ASDoc output
/build

asconfig.json

{
    "config": "air",
    "type": "app",
    "files": [
        "src/Main.as"
    ],
    "application": "app.xml",
    "compilerOptions": {
        "debug": true,
        "omit-trace-statements": false,
        "source-path": ["src"],
        "library-path": ["libs"],
        "output": "build/com.qux.foo.swf"
    }
}

src/Main.as

package
{
    import flash.display.Sprite;

    public class Main extends Sprite
    {
        public function Main()
        {
            // entry point
        }
    }
}

• apm init asconfig lib generates...
  • asconfig.json (replace com.qux.foo by the given id)
  • libs/.gitignore (empty .gitignore file)
  • swc/.gitignore
  • src (empty folder)
  • .gitignore
  • Other files for the APM project

.gitignore

# ignores build/docs only
/build

swc/.gitignore

# ignores asconfigc auto generated app descriptor
*.xml

asconfig.json

{
    "config": "air",
    "type": "lib",
    "compilerOptions": {
        "include-sources": ["src"],
        "library-path": ["libs"],
        "output": "swc/com.qux.foo.swc"
    }
}

apm asdoc

The asconfigc command supports building SWF/SWC and launching apps, but I think the contributor forgot the doc command (not sure).

The command apm asdoc requires an asconfig.json file. It should invoke aasdoc (not asdoc, which is for Flash Player only; while aasdoc is for Adobe AIR) using options from asconfig.json, including the compilerOptions. Here is the documentation for the asconfig.json file: https://github.com/BowlerHatLLC/vscode-as3mxml/wiki/asconfig.json

The command should output docs to build/docs.

Notes:

• The ASDoc command requires doc-sources instead of include-sources. So the asconfig.json field compilerOptions.include-sources translates to doc-sources. It looks basically like aasdoc -o=build/docs --doc-sources+=src.

https://repository.airsdk.dev API docs

I don't think it's easy to auto-generate API docs like Rust ecosystem does, but I believe there could be a repository so we can store our hand-generated docs there. Normally we can use GitHub Pages, but it's tedious to upload docs there manually.

APM already allows you to specify an URL to the API docs, but it's currently external to repository.airsdk.dev.

[hydroper]

It looks like aasdoc is failing to load SWCs via --library-path (discussion). So one idea is to merge library sources when running aasdoc (that is, --doc-sources+= for all dependencies sources). Of course this has one issue as it'll generate docs for unwanted libraries, so ASDoc needs some update.

[marchbold]

I have been looking into generating IDE configuration files and think this is a good idea. VSCode / asconfig is a good place to start so I have started some preliminary investigations here.

Regarding the documentation though, might start a separate discussion on this one as I'm not sure how we would handle this.

[hydroper]

@marchbold I ended up creating another discussion because this one got a little cluttered. I have organised a cleaner one.