Looks like @:forward() meta for abstract types is currently not supported.
http://haxe.org/manual/types-abstract-forward.html

The resource copying step currently doesn't support subdirectories. It should be changed to do a recursive copy.

Since #61 is merged, the output becomes:

When trying to generate dox pages from an openfl library there is a showstopper with the way a typedef is defined with UInt->Int https://github.com/openfl/openfl/blob/master/UInt.hx

#if !flash
typedef UInt = Int;
#end

I am not sure how to approach any workaround for this conflict, maybe change UInt.hx somehow just to generate dox here?

Uncaught exception - Incompatibilities between UInt in cpp and flash (module StdTypes should be null)

Any workaround would be helpful, I can generate the dox per target and its great on that front but then all the cool js menu etc is useless. Cheers.

It would be great to have support for tags like @param, @throws, @author, etc.

Not a new issue.

All the "specialized" versions should probably be ignored?

See the following post: HaxeFoundation/haxe.org#69

hi ,

iget this when trying to generate doc with dox

Parsing output.xml
Called from ? line 1
Called from dox/Dox.hx line 92
Called from C:\GitHub\haxe/std/haxe/rtti/XmlParser.hx line 84
Called from C:\GitHub\haxe/std/haxe/rtti/XmlParser.hx line 311
Called from C:\GitHub\haxe/std/haxe/rtti/XmlParser.hx line 321
Called from C:\GitHub\haxe/std/haxe/rtti/XmlParser.hx line 491
Called from C:\GitHub\haxe/std/haxe/xml/Fast.hx line 109
Called from a C function
Called from C:\GitHub\haxe/std/haxe/xml/Fast.hx line 123
Uncaught exception - Invalid field access : nodeType
Error: Command failed with error 1
[Finished in 1.5s with exit code 1]
[cmd: ['haxe', 'build.hxml']]
[dir: /Users/ut/Documents/Work/LAB/HAXELAB/SketchFramerPlugin]
[path: /usr/bin:/bin:/usr/sbin:/sbin]

-cmd haxelib run dox -r /dox -o output -i doc
haxe 3.01
dox :git version
os x moutain lion

any idea ?
thx

the typedef CodeBlock = Void->Void is being represented as "Codeblock = Void" and similar with Thunk<T> = T

My original idea was to support "view source" links by providing custom command line arguments and use them in the templates (see #50). However, as @aduros pointed out, there may be projects which require a more sophisticated handling of this.

An example is the Flambe API: https://aduros.com/flambe/api/
While types in the flambe package have their source on flambe github, types in the Haxe package should link to the Haxe github.

I'm not sure how to best approach this and make it configurable.

Thanks for great work on Dox and the Haxe API display!

Here's a humble suggestion:
I find the field- and methodnames hard to read with the current "code" style and small size. Below is an attached quick Firebug mockup where I changed some css attributes mainly for the code h3 styling + some more. I find that much easier to navigate...

Regards / Jonas

I thought we already implemented that, but apparently we didn't. It should be possible to see a list of all the fields that are available on a given class through inheritance.

Currently dox generates the entire .xml content, which for custom projects includes large portions of the haxe standard library.

I guess defining some regex filters via command line is good enough for now. In the long run we have to decide how to handle configuration in general.

#46 is working nicely, but it limits API docs to only one library / package - for example for flixel, we would like to provide the API for flixel / nape / OpenFL all conveniently in one place.

The --toplevel-package option could be turned into --toplevel-packages:

--toplevel-packages flixel, flixel.addons, flixel.addons.ui, nape, flash

Presentation-wise this could be done via an additional dropdown-menu next to the one for targets:

Using dox I get the following error:

$ haxelib run dox -r documentation/kraut.xml -o dox -i documentation
Parsing kraut.xml
Parsing template.xml
Called from ? line 1
Called from dox/Dox.hx line 87
Called from ws/haxe/std/haxe/rtti/XmlParser.hx line 84
Called from ws/haxe/std/haxe/rtti/XmlParser.hx line 311
Called from ws/haxe/std/haxe/rtti/XmlParser.hx line 322
Called from ws/haxe/std/haxe/rtti/XmlParser.hx line 306
Uncaught exception - Invalid head

I think there should be a better errormessage or even better, there should be only a warning about a file that can't be parsed.

Hello, I just compiled haxe3 development branch, neko2 and the haxelib dependencies for dox on Kubuntu 13.04 x64. The readme suggests haxe doc.hxml but this is not present maybe its renamed to run.hxml?

• I had to manually create mkdir ./bin/xml
• The xml files get created fine in the folder with haxe gen.hxml
• haxe gen.hxml runs without error
• haxe std.hxml gives me the following error:

$ haxe std.hxml 
Parsing cpp.xml
Parsing flash8.xml
Parsing java.xml
Parsing flash.xml
Parsing cs.xml
Parsing php.xml
Parsing js.xml
Parsing neko.xml
Processing types
...................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
Generating navigation
Called from ? line 1
Called from dox/Dox.hx line 100
Called from dox/Generator.hx line 44
Called from templo/Template.hx line 84
Called from templo/Template.hx line 91
Called from ws/haxe/std/neko/_std/Array.hx line 241
Called from templo/Template.hx line 127
Called from templo/Template.hx line 101
Called from templo/Template.hx line 221
Called from templo/Template.hx line 95
Called from templo/Template.hx line 175
Called from templo/Template.hx line 144
Called from templo/Template.hx line 91
Called from ws/haxe/std/neko/_std/Array.hx line 241
Called from templo/Template.hx line 120
Called from templo/Template.hx line 262
Called from templo/Template.hx line 243
Called from templo/Template.hx line 247
Called from templo/Template.hx line 277
Called from templo/Template.hx line 314
Uncaught exception - nav.mtt:14: Invalid call
Error: Command failed with error 1

Am I doing something wrong? thanks for this great project, you have created the best looking haxe docs out there.

Since the toplevel unfolding commit it seems.

Could look something like this:

/**
 * @default 5
 */
public var number = 5;

If I do:

haxe -lib nape -D doc-gen --no-output --macro "include('nape')" -xml a/x.xml
haxelib run dox -i a -o b

I get:

Parsing a/x.xml
Processing types
...............................................................................................................................................................Called from templo.Template::$statics line 1
Called from dox.Dox::main line 131
Called from dox.Processor::process line 26
Called from dox.Processor::processRoot line 147
Called from Lambda::iter line 148
Called from dox.Processor::processTree line 157
Called from Lambda::iter line 148
Called from dox.Processor::processTree line 157
Called from Lambda::iter line 148
Called from dox.Processor::processTree line 171
Called from Lambda::iter line 148
Called from dox.Processor::processClassField line 194
Called from dox.Processor::processDoc line 246
Called from dox.JavadocHandler::parse line 41
Called from dox.MarkdownHandler::markdownToHtml line 29
Called from Document::parseLines line 143
Called from markdown.TableSyntax::parse line 725
Called from EReg::map line 179
Uncaught exception - Invalid field access : length

This only happens with Nape. Most of my other libraries seem to work fine. I'm using HEAD on this repository.

In some cases it might be preferable to generate a singular .zip file instead of having Dox write each output file to the file system. We can add a --zip command line option to enable that.

The Readme is very confusing when in reality you need to run haxelib install dox, then haxelib run dox [params].

When you scrolldown to see some function, that is near the end of the page, the package and class-name is away.

I had to often scroll up and down, because of forgetting the correct spelling of the classname or the order of parameters on your gh-pages.

If you could provide a fixed part, where this information is clearly visible, that would be really awesome!

The left-hand and top-level navigation from dox appears to be broken, when exporting documentation for OpenFL.

This appears to work when all classes are included, but when including only "openfl" in order to filter out the Haxe core classes, this is broken:

http://www.openfl.org/documentation/api/

Originally, the index.html showed "top-level" with no contents. As a fast workaround at the moment, I copied the contents of "pages/openfl" into the root directory, to give more meaningful output, but it would be awesome to have a real fix :)

Thanks!

Would it be possible to bundle bootstrap and jquery instead of loading them from other domains? This would make it possible to read dox offline.

Currently empty packages are shown in the navigation.
By empty I mean a package with all of its classes with @:dox(hide).
It would make more sense to not add them.

dox adds a ? for parameters that have default values, like here:

public function new(X:Float = 0, Y:Float = 0, ?SimpleGraphic:Dynamic)

However, this is misleading, since the question marks imply nullability. So basic types like Int will turn into Null<Int>, which is not the case here, and can lead to some confusion.

Related: HaxeFoundation/haxe#2561

Hello, I just compiled haxe3 development branch, neko2 and the haxelib dependencies for dox on Kubuntu 13.04 x64. The readme suggests haxe doc.hxml but this is not present maybe its renamed to run.hxml?

• haxe run.hxml runs without error
• I had to manually create mkdir ./bin/xml
• The xml files get created fine in the folder with haxe gen.hxml
• haxe std.hxml gives me the following error:

$ haxe std.hxml 
Parsing cpp.xml
Parsing flash8.xml
Parsing java.xml
Parsing flash.xml
Parsing cs.xml
Parsing php.xml
Parsing js.xml
Parsing neko.xml
Processing types
...................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................
Generating navigation
Called from ? line 1
Called from dox/Dox.hx line 100
Called from dox/Generator.hx line 44
Called from templo/Template.hx line 84
Called from templo/Template.hx line 91
Called from ws/haxe/std/neko/_std/Array.hx line 241
Called from templo/Template.hx line 127
Called from templo/Template.hx line 101
Called from templo/Template.hx line 221
Called from templo/Template.hx line 95
Called from templo/Template.hx line 175
Called from templo/Template.hx line 144
Called from templo/Template.hx line 91
Called from ws/haxe/std/neko/_std/Array.hx line 241
Called from templo/Template.hx line 120
Called from templo/Template.hx line 262
Called from templo/Template.hx line 243
Called from templo/Template.hx line 247
Called from templo/Template.hx line 277
Called from templo/Template.hx line 314
Uncaught exception - nav.mtt:14: Invalid call
Error: Command failed with error 1

Am I doing something wrong?

Also running from dox in haxelib haxelib run dox -i ./bin/
Gives me a similar error with the navigation generation:

Processing types

Generating navigation
Called from ? line 1
Called from dox/Dox.hx line 100
Called from dox/Generator.hx line 44
Called from templo/Template.hx line 84
Called from templo/Template.hx line 91
Called from ws/haxe/std/neko/_std/Array.hx line 241
Called from templo/Template.hx line 127
Called from templo/Template.hx line 101
Called from templo/Template.hx line 221
Called from templo/Template.hx line 95
Called from templo/Template.hx line 175
Called from templo/Template.hx line 144
Called from templo/Template.hx line 91
Called from ws/haxe/std/neko/_std/Array.hx line 241
Called from templo/Template.hx line 120
Called from templo/Template.hx line 262
Called from templo/Template.hx line 243
Called from templo/Template.hx line 247
Called from templo/Template.hx line 277
Called from templo/Template.hx line 314
Uncaught exception - nav.mtt:14: Invalid call

Thanks for this great project, you have created the best looking haxe docs out there.

Perhaps when no "document root" has been specified, it should use relative paths, instead of hard-coding to the locations on the current system? When distributing OpenFL, it would be nice if users could open the documentation on their local file system, in addition to it working online. Thanks!

When invoked with ´$ haxelib run dox -r documentation/kraut.xml -o dox -i documentation`, which should generate the documentation from documentation/kraut.xml into dox/, as far as I understand it, then I can open every file by itself, but I don't have a navbar on the left side and the generated links are some kind of wrong, eg: file:///home/nmelzer/projects/haXe/kraut/haxelib/dox/documentation/kraut.xml/Kraut.html

but there is no documantation folder under dox

Example: js/html/idb/Index.html

Dox will try to generate this as Index.html, while also generating the package information as index.html. This does not work on Windows.

While I like the fact that all pages are static .html, the total file size is going a bit out of control for the ~1900 files we generate for the haxe standard library. The nav easily adds 100kb to each single page.

Hi!
I am currently using chxdoc, but plan on switching to Dox in a near future (next projects).

Dox really seems good, but there are still some functionalities from chxdoc that I would miss:

• Ability to generate docs for private vars, methods, typedefs, classes and enums, mainly for private full API documentation.
• @todo Description For generating TODO files and html notes. This one seems a bit off-topic but I'm using it with the private full API doc. I could use other tools for this one, though.
• @see Description Adds description as a source to view
• Embedded tags like {@link } for things like @see {@link haxe.io.Bytes}. Not implemented in chxdoc, but I added it locally and use it a lot.
• Handling of "code" sequences in javadoc, in the form of [text to transform] in chxdoc. Generates a <code> tag (and strips the []).

I can't use Dox for now since I am using an older version of Haxe, so some of these may be already available with Dox.

Looking at http://haxeui.org/docs/api/haxe/ui/toolkit/index.html, you have to click into haxe, ui and toolkit before getting any useful information. We should either allow specifying a toplevel package, or fold one-element packages by default so the navigation shows "haxe.ui.tookit" as a single entry.

-i expects a path to a directory, not a file. If the user includes the file at the end of the path the program terminates.

While not required at the moment, I'm sure people are going to request all kinds of configuration options. At some point we're going to need some sort of configuration file support.

I suggest that we use JSON and deploy dox with a standard config.json. When running dox it reads that file and applies the options accordingly. After that we process command line arguments, where we allow a new -config <path> argument. That file is then read and override the previous options. Finally, command line arguments are processed as usual and may again override specific options.

Any thoughts? I would like to work on this, but we should merge #33 before that.

Hi David,

Looks like documentation on typedef properties don't format correctly.

For example

typedef Foo = 
{
    /**
        Some description with a type reference 'Foo'.

        And a Second Line
                `"type":"ItemDetail"`
    **/
    var bar:String;
}

Outputs docs as a single line of plain text:

Some description with a type reference 'Foo'. And a Second Line `"type":"ItemDetail"`

given this signature

public static function delay(callback : Void -> Void, delay : Int) : Void -> Void

The generated documentation reports:

static function delay(callback:Void, delay:Int):Void

E.g. here http://api.haxe.org/haxe/web/Redirect.html the package in the import statement should redirect to the API page for that class.

It would be nice to allow a command line argument like Haxe's -D key=value and add an API method to access values by keys, which could then be used in the templates.

A use-case example are "View source" links, which typically require a custom, common base path.

/**
  @param x some documentation for parameters.
**/
public function foo(x:Int):Void
{
}

The @param is not recognized after a467b60

You know what I mean.

Sometimes you have a base class/interface that has a documented method, then you override/implement that method in a subclass. It would be nice not to have to write documentation for that new method.

Example: https://aduros.com/flambe/api/flambe/display/EmitterSprite.html#draw might inherit the doc of https://aduros.com/flambe/api/flambe/display/Sprite.html#draw

Javadoc has an explicit @inheritdoc tag for this. Maybe we could even make it implicit if the override has no doc? I don't why you wouldn't want to inheritDoc in that case.

/**
 * Creates a FlxSprite at a specified position with a specified one-frame graphic. 
 * If none is provided, a 16x16 image of the HaxeFlixel logo is used.
 * 
 * @param   X               The initial X position of the sprite.
 * @param   Y               The initial Y position of the sprite.
 * @param   SimpleGraphic   The graphic you want to display (OPTIONAL - for simple stuff only, do NOT use for animated images!).
 */

Note the additional asterisks at line ends in the screenshot. They should be ignored.

I've implemented a very basic themes handling for dox to allow grouping together templates and resources. You can see the example themes (our current default and the one from pull request #30 here): https://github.com/Simn/dox/tree/themes/themes

The idea is to allow users to simply create a new theme directory with a config.json and inherit from an existing theme, overwriting its resources and templates partially or completely. Themes can then be switched via a command line -theme name argument.

Do you think this has merit? Any thought on what else we'd have to consider?

For example, FileSystem should be hidden in http://api.haxe.org/sys/index.html when the user choose flash platform.

A small cosmetic issue,
when using a hexadecimal value in the code, for stuff like color: color:Int = 0xFFFFFF
end up looking like this ?color:Int = 16777215 which is kind of weird.

No idea how to fix that though,
maybe something like a parameter to @param like @param(hex)?

It would make going through the documentation of e.g. the haxe.macro.* package much easier if a small preview appeared for typedefs, so it's not needed to click on a type (for example, haxe.macro.Catch) to see what it does.

Thanks for the great work!

It's fairly common to have comment-style that looks like this:

/**
 * This is a comment
 * that spans multiple
 * lines.
 */

Could the leading asterisks be trimmed so that this doesn't get turned into a bullet list when run through markdown? I bugged Simon about this the other day. Ideally, it could infer the comment style automatically rather than a new flag.

This is a regression, not sure from when exactly.

Previously:

Now: