Icefox's picture

OpenTK API reference

I feel somewhat silly asking this since it's so trivial, but I'm somewhat new to .NET in general, so...

Is there some API reference documentation for OpenTK? I can't find any such thing on the website, just the tutorial docs... I'm going through those to test, update and learn, but having a HTML API reference would be really handy. MonoDevelop doesn't seem to have any way of generating that from the source, and monodoc doesn't appear to work on Windows; am I just looking in the wrong place?


Comments

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.
the Fiddler's picture

Sorry, no good solution yet but this is being worked on.

In theory, the attached XSLT should transform OpenTK.xml into a valid HTML function reference. You can test this theory by saving OpenTK.xml, OpenTK.xslt and OpenTK.css into the same folder then editing OpenTK.xml to start with those lines:

<?xml version="1.0"?>
<?xml-stylesheet href="OpenTK.xslt" type="text/xsl"?>

Afterwards, just open OpenTK.xml with a browser. (Warning: the file takes a long time to load and may cause the browser to hang during this time. Better open on a different window. Surprisingly, Internet Explorer 8 seems to be handle this file quite well.)

AttachmentSize
OpenTK.css2.18 KB
OpenTK.xslt6.57 KB
Icefox's picture

Aha, that incantation actually works quite well. Thank you!

I'd like to contribute to OpenTK in my Copious Free Time (of which I have none), and given that I'm not really an expert in OpenGL, OpenAL or C#... documentation seems like a good place to start. I've done what I can on the documentation pages, and am planning to add more; do you have any suggestions of where to start or how you want this to be handled? If not, I'll probably try to run OpenTK through Doxygen, or possibly try to turn the OpenTK.xml file into something more useful, and work from there. I can host whatever I get on my own site until it gets to a useful state, if necessary.

the Fiddler's picture

Charles has created an awesome patch that, between other things, uses Sandcastle to generate documentation. The downside of this approach is that it is windows-only, which doesn't really fit the cross-platform approach of OpenTK. Right now, I'm playing with mdoc which comes with Mono (available on all operating systems):

mdoc update OpenTK.dll --import OpenTK.xml --out docs

I'm pretty sure the output can be converted to html to avoid the need for monodoc (haven't read the docs yet).

Icefox's picture

Here is what Doxygen trivially spits out, generated with Doxywizard:
http://alopex.li/temp/html/
Doxygen config at:
http://alopex.li/temp/opentk-1.0-beta2.doxygen
And the whole thing can be downloaded at:
http://alopex.li/temp/opentk-1.0-beta2-doc.zip (4 MB)

These files should stick around for a month or two at least, but this is still just a test. I think it's better than XML, at least. It's a bit weird still of course; the class list seems to go in order of the class name rather than the namespace hierarchy, for instance. I'll keep playing with it and see what I can do.

I'm not impressed with what little I've seen of Sandcastle so far, but I'll take another look at it. I'll also have to play with monodoc and see if I can coax it to produce something reasonable... I'm a bit dubious of the DLL+XML approach on principle, but we'll see what works.

Icefox's picture

mdoc works, using :

mdoc update OpenTK.dll --import OpenTK.xml --out docs
mdoc export-html -o mdoc docs

http://alopex.li/temp/mdoc/
http://alopex.li/temp/opentk-1.0-beta2-mdoc.zip (2.8 MB)

mdoc has some plusses; it integrates with Mono/.NET's built-in documentation store, and is distributed with Mono. However, it'd feel a bit silly to make people install Mono to build the documentation, if they're using the library with MS .NET. It also takes a good two hours to grind its way through everything.

Sandcastle output:
http://alopex.li/temp/Help/
http://alopex.li/temp/Help.zip (37 MB)
Upon consideration, Sandcastle actually produces some fairly nice output, though getting it to actually work is rather irritating and it takes half an hour to process everything. There are myriad tiny things I don't like about it... Windows only, takes a long time and doesn't handle rebuilds well, the frames make bookmarks not work, it generates a ton of files, the file names are entirely opaque, but the end results are admittedly pretty.

NDoc, alas, seems to disagree with any version of .NET beyond 1.1. I couldn't coax it into working, so it's out of the running.

In the end, I like Doxygen the most: fast, pretty, outputs lots of file formats, and is easy to make work. I suppose mdoc and Sandcastle are tied for second. Both are vendor-specific. Both appear to mainly generate documentation for local viewing (monodoc vs. .chm file), with website generation tacked on afterward. Both generate from assembly + xml file, rather than from source code directly like Doxygen. Both take a long time to generate everything. mdoc is a lot easier to use, a lot slower, and produces uglier output (or at least output that will need some custom stylesheeting). Sandcastle is half-undocumented, a royal pain to make work, and produces really pretty results.

It's all a pile of tradeoffs. Depends on what you want in the end, Fiddler.

the Fiddler's picture

Thanks for putting this together. I wasn't aware that doxygen supported ECMA--334 doc comments, I just tried this out and the results are awesome!

The function reference is now available online. I will also add a "doc" target to Build.exe that will invoke doxygen with the specific documentation used for the online docs.

The nice thing about doxygen is that:

  1. It is cross-platform
  2. It can generate html and pdf docs
  3. It is fast! Running on a SSD probably helps, but generating documentation takes less than 60'' on my machine.
  4. It can be instructed to ignore private members, as well as members marked as "\internal". This is very useful for OpenTK, because almost everything inside OpenTK.Platform should be hidden.

All in all, I think that's the way forward.

Icefox's picture

All right, I'm glad I could help! If there's anything else I could do to aid with documentation, just let me know. I should probably try to work more on tutorial docs... once I learn enough about OpenTK myself. :)

Hortus Longus's picture
the Fiddler wrote:

... All in all, I think that's the way forward.

As I said here, http://www.opentk.com/node/1222#comment-6976, Doxygen can be quite useful. :-)

If you like it, I can check up the Doxy-Tools in my company whether some more meaningful for you.
You can give me a list (PM), what you would like for relief.

--
The most fundamental problem in software development is complexity. There is only one basic way of dealing with complexity: Divide and conquer.

the Fiddler's picture

Thanks for the offer. I'm still exploring the capabilities of the tool but I'll ask if I need any help.

I wasn't aware that doxygen could understand C#-style comments, I always thought needed its own /** */ format. Now I know better. :)

KernelInfernal's picture
Icefox wrote:

mdoc works, using :

mdoc update OpenTK.dll --import OpenTK.xml --out docs
mdoc export-html -o mdoc docs

http://alopex.li/temp/mdoc/
http://alopex.li/temp/opentk-1.0-beta2-mdoc.zip (2.8 MB)

mdoc has some plusses; it integrates with Mono/.NET's built-in documentation store, and is distributed with Mono. However, it'd feel a bit silly to make people install Mono to build the documentation, if they're using the library with MS .NET. It also takes a good two hours to grind its way through everything.

Sandcastle output:
http://alopex.li/temp/Help/
http://alopex.li/temp/Help.zip (37 MB)
Upon consideration, Sandcastle actually produces some fairly nice output, though getting it to actually work is rather irritating and it takes half an hour to process everything. There are myriad tiny things I don't like about it... Windows only, takes a long time and doesn't handle rebuilds well, the frames make bookmarks not work, it generates a ton of files, the file names are entirely opaque, but the end results are admittedly pretty.

NDoc, alas, seems to disagree with any version of .NET beyond 1.1. I couldn't coax it into working, so it's out of the running.

In the end, I like Doxygen the most: fast, pretty, outputs lots of file formats, and is easy to make work. I suppose mdoc and Sandcastle are tied for second. Both are vendor-specific. Both appear to mainly generate documentation for local viewing (monodoc vs. .chm file), with website generation tacked on afterward. Both generate from assembly + xml file, rather than from source code directly like Doxygen. Both take a long time to generate everything. mdoc is a lot easier to use, a lot slower, and produces uglier output (or at least output that will need some custom stylesheeting). Sandcastle is half-undocumented, a royal pain to make work, and produces really pretty results.

It's all a pile of tradeoffs. Depends on what you want in the end, Fiddler.

The links are not working anymore, please update.