Dox support for haxelibs

[jasononeil]

It would be good to discuss this.

Is the plan to include haxelibs on "api.haxe.org"? Or should generated documentation be included on the "lib.haxe.org" website? (If the verdict is that they belong on api.haxe.org, it may be suitable to host this discussion elsewhere).

Secondly, dox can support input from multiple Xml files, but the previous haxelib website only looked at a single "haxelib.xml" file. I imagine the options are:

• Only support one Xml file. Possibly provide a way to merge stuff before submitting
• Have a "dox" folder which contains all the XML files
• Let people upload their compiled "dox" folder already - but then they could upload any HTML.
• Extend the haxelib.json specification to allow you to specify your documentation files.
• Manually generate the Xml using import macros and the specified classPath, then produce the dox.

On top of this, dox gives you some options for filtering packages etc. Do we want to let the library maintainer specify these settings manually?

Also, it would be nice to access documentation for all versions of a library that have been uploaded.

[back2dos]

As I've pointed out in haxedev, the tricky part is handling dependencies in documentation.

Say you have a dependency chain as tink_core < tink_macros < tink_lang < tink_reactive < tinx_node < tinx_nw, will each documentation contain Ouctome?

There is a growing trend to dissect libraries into multiple interdependent parts. Off the top of my hat, I would think of ufront, OpenFL and PrimeVC - just to name a few. So I believe this is an important question to deal with.

Managing to link between interdependent libraries rather than duplicating documentation again and again is not only less resource intense, but I think it also helps communicating which modules belong to which libraries.

I've looked at how it's currently implemented:

You get some documentation here: http://lib.haxe.org/legacy/d/mpartial/1.2.1/mpartial/FilePrinter This depends on a class from mconsole, to which there is a (currently broken and therefore corrected here) link: http://lib.haxe.org/legacy/d/mpartial/1.2.1/mconsole/FilePrinter

Because there's no documentation for it in the supplied haxedoc.xml, it is assumed that you're looking for a class from the std lib and will therefore be redirected to the wiki at http://haxe.org/api/mconsole/fileprinter

---

As for the issue with single/multiple xml files, why not just use .dox (or .dox.xml or .haxedoc.xml or whatever ...) as an extension for xmls that contain haxe documentation and simply scan for all files with that extension?

[jasononeil]

And that is where it gets interesting :)

If during generation of the docs (or if the docs are generated dynamically), we could have an algorithm that tries to find the "canonical" version of that type:

• does the type exist in the sys library? Which version? Redirect there.
• does the type exist in a dependant library? Which version? Redirect there.
• or else assume the type belongs to this library, generate docs here.

You could also compare against the classPath as an option, though then you are required to process the zip file not just the XML files.

Having a canonical address for the documentation of a particular class may also have benefits if user generated documentation is ever included in future docs, which, if it is better structured than a simple comment field, may actually be quite helpful.

Of course, that would significantly increase the scope of the issue in question :)

As I've pointed out in haxedev, the tricky part is handling dependencies in documentation.

Say you have a dependency chain as tink_core < tink_macros < tink_lang < tink_reactive < tinx_node < tinx_nw, will each documentation contain Ouctome ?

There is a growing trend to dissect libraries into multiple interdependent parts. Off the top of my hat, I would think of ufront, OpenFL and PrimeVC - just to name a few. So I believe this is an important question to deal with.

Managing to link between interdependent libraries rather than duplicating documentation again and again is not only less resource intense, but I think it also helps communicating which modules belong to which libraries.

I've looked at how it's currently implemented:

You get some documentation here: http://lib.haxe.org/legacy/d/mpartial/1.2.1/mpartial/FilePrinter This depends on a class from mconsole, to which there is a (currently broken and therefore corrected here) link: http://lib.haxe.org/legacy/d/mpartial/1.2.1/mconsole/FilePrinter

Because there's no documentation for it in the supplied haxedoc.xml, it is assumed that you're looking for a class from the std lib and will therefore

be redirected to the wiki at http://haxe.org/api/mconsole/fileprinter

As for the issue with single/multiple xml files, why not just use .dox (or .dox.xml or .haxedoc.xml or whatever ...) as an extension for xmls that contain haxe documentation and simply scan for all files with that extension?

— Reply to this email directly or view it on GitHubhttps://github.com/HaxeFoundation/haxelib/issues/69#issuecomment-20038555 .

[Simn]

What's the state here? Is there anything we could help you with from the Dox side of things?