Help with dox and openfl

yuumi · May 10, 2020, 8:58pm

Hello!
I’m new to Haxe, OpenFL and dox, please be patient with me

I’m trying to generate documentation with dox for a library (there is no main class).
However I’m having trouble when including OpenFL. (Several classes in my library includes OpenFL classes).

I’m using Haxe 4.0.5, OpenFL 8.9.6 and dox 1.5.0.

Here’s my hxml:

-cp src
--macro include("mylib", true)
-L openfl:8.9.6
-D doc-gen
--no-output
-xml doc/doc.xml

--next
-cmd haxelib run dox -i doc -o doc/pages -in "^mylib*"

The error msg I get:

/usr/local/lib/haxe/lib/openfl/8,9,6/src/openfl/_internal/text/TextEngine.hx:132: characters 17-29 : (t : openfl._Vector.IVector<Unknown<0>>, length : Int, fixed : Bool, array : Array<Unknown<0>>) -> openfl._Vector.FloatVector should be openfl._Vector.IVector<Float> -> openfl._Vector.FloatVector

If I remove all OpenFL dependencies I have no trouble generating docs, so I think my problem is related to OpenFL? I’ve tried including just a few OpenFL classes, eg:

import openfl.utils.Object;
import openfl.utils.Assets;

It works with only Object but not with Assets. I presume Assets uses TextEngine in some way?
Any help would be appreciated!
Thank you

joshtynjala · May 11, 2020, 12:46am

Here’s my working dox hxml for Feathers UI:

github.com

BowlerHatLLC/feathersui-openfl/blob/master/docs/docs.hxml

-cp ../src
-D doc-gen
-D display
-lib lime
-lib openfl
-lib actuate
--remap flash:openfl
--macro ImportAll.run("feathers")
--no-output
--interp
-xml ../build/xml/feathers.xml

--next
-cmd haxelib run dox -o ../build/api -i ../build/xml -in feathers --title "Feathers UI API Reference (Haxe/OpenFL)" --toplevel-package feathers -theme ./feathersui-theme -D website "https://feathersui.com" -D textColor 0x292522 -D source-path "https://github.com/BowlerHatLLC/feathersui-openfl/tree/master/src/"

It took me a bit to figure out how to make dox work as expected. I tried to use the include macro, like they suggest in the instructions, but it never seemed to work. I ended up finding this ImportAll class (from the official Haxe repo, I think) that worked better:

github.com

BowlerHatLLC/feathersui-openfl/blob/master/docs/ImportAll.hx

import haxe.macro.Context;
import sys.FileSystem;

// stolen from haxe/doc/ImportAll.hx
class ImportAll {
	static function isSysTarget() {
		return Context.defined("neko") || Context.defined("php") || Context.defined("cpp") || Context.defined("java") || Context.defined("python")
			|| Context.defined("lua") || Context.defined("hl") || Context.defined("eval"); // TODO: have to add cs here, SPOD gets in the way at the moment
	}

	public static function run(?pack) {
		if (pack == null) {
			pack = "";
			haxe.macro.Compiler.define("doc_gen");
		}
		if (Context.defined("interp")) {
			haxe.macro.Compiler.define("macro");
		}
		switch (pack) {
			case "php7":

This file has been truncated. show original

yuumi · May 11, 2020, 9:16am

Thank you so much! This worked

Gama11 · May 13, 2020, 9:55am

I think there’s no need to do this manually with a hxml actually, the lime command has a -xml flag. That’s what Flixel uses.

joshtynjala · June 24, 2020, 6:38pm

Finally got around to trying this -xml flag to generate the documentation. Works great! Thanks.

VishwasGagrani · July 1, 2020, 3:23am

Is there any way I can use dox command to generate document only for the package I want. Right now it creates a huge xml also including a lot of Classes and Functions that I don’t want. I usually don’t have more than 10-15 classes in my projects. The documents generated by dox becomes overwhelming.

joshtynjala · July 1, 2020, 3:43pm

I use the include macro to generate documentation for Feathers UI. Here’s what I added to my project.xml:

<haxeflag name="--macro" value="include('feathers')"/>

Gama11 · July 2, 2020, 6:54am

dox has a --toplevel-package argument, as well as --include. See here or haxelib run dox --help.