jsdoc3-hxtern

Jsdoc3-hxtern is a Jsdoc plugin that uses extended closure compiler annotations in order to generate Haxe externs.

It's currently in an incomplete alpha state.

Basic workflow

You use jsdoc3-hxtern with jsdoc as follows:

jsdoc -t /path/to/jsdoc3-hxtern some_js_library.js

The haxe externs will be written to a directory called "out" in the current working directory. See the documentation for jsdoc command line options for more details.

jsdoc3-hxtern works by plugging directly into jsdoc, extracting individual methods, variables, modules, and classes, and then expanding the type information there using a special closure compiler-comaptible parser called doctrine.

After doclets are extracted and type information gathered from doctrine, there are still several situations that require special handling.

1. It's typical to have static methods attached to "modules" in javascript, rather than to a "class". E.g. if there were a module of "foo.bar", it's you might see a method defined like this:

   foo.bar.baz = function(){...}

   In Haxe, this isn't possible. Haxe requires that you define methods only on classes. And classes must be upper case. To work around this problem, Hxtern converts the last module into an "alias" class, and attaches the method to that instead:

   package foo;
   @:native("foo.bar")
   class Bar {
      public static function baz(){...}
   }

   The upper class alias can coexist along side the lower class module with no problems. however, If there's already an additional Bar class in the js file, then the process will fail.

2. Hxtern tries to convert js types and jsdoc tags to Haxe equivalents. Here's an (incomplete) list:

      boolean  -> Bool;
      string   -> String;
      Array    -> Array;
      number   -> Float;
      Object   -> Dynamic;
      Function -> Dynamic;
      void     -> Void;
   

   Further transformations are possible depending on type details... e.g. Object<string, number> will get translated to Map<String,Float>.

3. Hxtern will change the name of callback arguments to avoid using haxe keywords. It will prepend a '_' character to arguments named "callback".

4. Haxe does not have a traditional ellipses operator for arguments (e.g. a function that accepts an arbitrary number of arguments. When Hxtern encounters one of these it will generate 6 optional arguments in its place.

5. Haxe does not have "union types" that are sometimes used to describe the arguments of a method (either a string or an int). Currently, the plugin just treats these as "Dynamic" types.

TODO

• handle @extends
• handle union types
• handle methods, variables, etc. that do not have documentation