the Fiddler's picture

(blog) Thoughts on OpenTK documentation

This question makes me think. Do you consider OpenTK well-documented? What parts do you consider lacking? What would you like to see?

I don't really know where OpenTK is standing in the documentation issue. According to Ohloh, 30% of all source code lines are comments, which is higher than average (22%). Considering OpenTK contains around 850000 lines of code, this number is nothing to laugh at. (Yeah, the numbers are probably overblown, no I have no idea how they are calculated :-).)

OpenTK is built on the premise that you are using an IDE with code-completion and documentation tooltips. Used on its own, it is actually more complex than straight OpenGL or OpenAL. This additional complexity is spent on type-safety and function overloads that smooth the differences between .Net and native code, which is a major win when using a .Net IDE like Visual Studio, MonoDevelop or SharpDevelop.

Is OpenTK usable without an IDE? Certainly, but the experience will not be as smooth. Strongly-typed parameters and function overloads won't help if you cannot discover them in the first place. So if gedit and make are your cup of tea then OpenTK might not be the optimal choice (but do check whether your editor supports .Net code completion - many do!)

Of course this doesn't say anything about the quality or usefulness of the documentation, so if you have any thoughts or suggestions I'd love to hear them.


Comments

Comment viewing options

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

Hello all, I'm new to the forums, hopefully I can provide some insight as a new user (both to OpenTK and OpenGL).

The code completion definitely helps, as most of the GL methods exposed have their docstrings displayed, and the enum names help out a lot. The one thing where I get tripped up on is mainly OpenGL semantics, especially since I'm used to XNA (e.g. I didn't know you had to bind colors, textures, etc.), but I'm guessing that falls out of the realm of OpenTK-specific documentation.

If anything, I feel like the official website API and docs could use a bit more love, especially by more advanced and familiar users of both TK and GL. There have been some issues when starting out my project that haven't been in the tutorials, but were explained nicely in the forums.

On that note, the forums are a huge help to the novice OpenTK'er, the community seems to be really helpful and friendly, and are probably the best source of "documentation". :D

mitsol8's picture

I have never used OpenTK without an IDE. I will never try to implement code without an IDE, from scripting to compiled languages.

thethirdhalf's picture

I have little experience with OpenTK, but I am starting to use it. As a software engineer, I would rather see self-documenting code than documentation about the code. Now, where this doesn't work is leaky abstractions. If an abstraction was ideal, it would have no leaks. There would be no 'gotchyas', no considerations from the underlying encapsulated system(s) that we would need to be aware of.

As an example, a cell phone abstracts away the reality that a digitally encoded message is being transmitted via a carrier signal. Most people could not care less - except when can't place a call. The buttons or touchscreen, the user interface, etc. are all an abstraction to hide the complexities of transmitting voice to a remote location. And for the most part, the abstraction holds. But when the signal is poor, it 'leaks' - the abstraction cannot conceal and encapsulate the underlying system adequately to shield the user from the actual realities of the system.

That is, I think, the real challenge of documentation in an API: Design a self-documenting interface, insofar as it is possible, provide tests that illustrate its usage (unit or acceptance tests are in my view better than examples, if they are developed behaviourally), and then document the leakiness of the various abstractions. Explain the context of each part of the system, so that the self-documenting code is easier to understand in the whole. Explain broad design intention and compromises in the implementation. I am familiar with OpenGL, and aside from being a configuration management nightmare, it is an apt illustration of a very non-self-documenting API.

Just some thoughts! And again, I'm not actually too familiar with OpenTK, so I'm not thinking of anything specific with this API, but I'm pretty excited to get into it.

invisghost's picture

IMHO you shouldn't try to take into account people who use and IDE without intellisense. Most of the .Net libraries are designed assuming that you either know the properties, types, and parameters or that you have a easily accessible way of finding out (intellisense).

I think it'd be nice to have the documentation to support exploratory programming. Just typing "GL." and going down the list seeing what everything does. OpenTK shouldn't try and teach OpenGL in the documentation but at least explain what things do. I'd like to not have to jump back and forth from my code and the OpenGL specification as much as i currently have to.

When it comes to certain areas that are missing I'd have to say that the Enums should be the first things taken care of and then (if you want) the GL.* methods. The method names are pretty self explanatory so that's why I think Enums should be documented first.

Bottom line:
Does it help: Yes.
Does it hurt: No.

the Fiddler's picture

SVN trunk now contains much more extensive documentation on the GL.* methods. Unfortunately, Khronos doesn't provide any explicit documentation for enums. I wonder how feasible it would be to extract the necessary information from the documentation on method parameters (which do cover enums).

invisghost's picture

It would be worth doing for the popular enums at least ( EnableCap, StringName, etc... )