[SOLVED] Documenting code workflow

Hello,
I’m trying to create a workflow to make documentation easy.

I’ve dig google, the old haxe forum (nothing on the new website) and this forum…
Lots of pieces around, but nothing complete.

I don’t have HAXEDOC in my /usr/bin (was this tool dropped? is there a way to get it?)
so I’ve chosen DOX ( http://github.com/dpeek/dox ) which is not too bad actually.


The first step is creating the XML file.

The only way I’ve found working is putting an haxeflag in my project.xml

<haxeflag name="-xml" value="bin/doc.xml" />

and then launch

lime build neko

this make the file doc.xml


I’ve tried

lime build neko -xml bin/doc.xml

but it says

Error: You must have a “project.xml” file or specify another valid project file when using the ‘build’ command


I’ve tried haxe with a docs.hxml but that way I can document only the haxe library, nothing mine. if I specify the -cp src and -lib openfl -lib lime it doesn’t work)


The second step is compiling with dox

I launch

haxelib run dox -i bin -o docs

and it works perfectly

but I find documentation compiled for EVERY class in haxe and openfl (and obviously every other haxelib included in my project)


So,
what is your workflow to make documentation?
Because right now I can’t figure it out how to build an xml with ONLY my package.

Thanks
Yup

The haxedoc tool was drop, since haxe 3 or 3.1 I think, and it doesn’t work with the latest versions,
but dox is great, and it’s the only documention tool maintained as far as I know.

You can use the dox option -in my.package to get only the doc for your project, if you put your code in a package.

Thank you @ibilon, this was exactly what I was looking for. I read the help print in dox but I didn’t understand these lines where talking about the packages

[-in | --include] <regex>      : Add a path include filter
[-ex | --exclude] <regex>      : Add a path exclude filter

In the end I’m doing like this

Workflow

make xml files

lime build neko --haxeflag='-xml bin/doc.xml'

make html documentation

haxelib run dox -i bin -o docs -in com

But there is something else I don’t understand.

The class I’m trying to document is called com.akifox.transform.Transformation
If I write dox [...] -in com it works (only the com tree is included)
but if I specify dox [...] -in com.akifox nothing get processed

why?

I want to document only THAT tree, no all the COM tree (which can contain other stuff).
Any idea?

It’s supposed to be a regex so maybe you’d need to escape the point -in com\.akifox or maybe try -in akifox.

I understand what you mean but no.

a . (dot) in a regex means ‘every one char’ so it would have to work anyway.

everything in a second level doesn’t render at all

ie:

-in 'openfl' -> works
-in 'openfl\.display' -> doesn’t work
-in 'display' -> doesn’t work

The XML argument is not supposed to accept a path:

openfl build neko -xml

Depending on the platform you are building, it will put the file in “Export//types.xml”, which could be used elsewhere. Since Dox does the platforms based upon the file name, perhaps this should be “Windows.xml” instead of types.xml

Another idea would be to add Dox support to the new openfl deploy command:

openfl deploy neko -dox

Thank Joshua for the answer,
Now I understand why lime build neko -xml [path] was not working.
My fault I didn’t read the help but I’ve just assumed it was the same as haxe

Basically right now I am using this method:

The script gen_doc.sh removes all the files from the XML folder and the DOCS folder (the one which will receive the dox ed html files)
then it runs the compilation on every platform using gen_doc.hxml
and in the end runs dox with input the XML folder and output the DOCS folder.

It is quite good like this (tell me if I could improve it, as a newbie I am trying to make the things work, but for sure I will not find the best way at first try), the only problem is about the -in parameter in dox

I don’t know how to include only the package in a depth level higher than one

As I said something like -in openfl works, but not -in openfl.display.

Ideas?

PS: maybe this is stupid but can I ask you if is there any difference if I use the command openfl or lime? I can’t really see any difference. I know the difference between lime and openfl, but not the difference in the CLI.

I’m not sure if I’ve gotten that to work. I filter based on top level packages, but I understand the issue :confused:

lime and openfl use the same Lime tool, openfl uses teal instead of green, it uses an “OpenFL” welcome message, and changes the implied behavior of things like lime create project MyProject vs. openfl create project MyProject. Largely, it’s about what comes most naturally to you :slight_smile:

I’ve actually tried with the very OPENFL and OPENFL.DISPLAY for testing.
It doesn’t work.

I think it might be a bug. (or maybe I am using it wrong)
I’ve submitted an issue on the repository.
We will see if it’s me (most probably) or a real bug.

Might be a bug, you might also try “-ex” or perhaps the Github version of Dox is patched already

I was thinking the same.
I am already on the github version (haxelib git) and I’ve tried -ex as well.

It was a bug.
Fixed

1 Like