Documentation for 1.6? Or 1.7?

playerdark · Post by **playerdark** » Mon Mar 23, 2009 5:54 am

I am working with irrlicht for a while now and my project is pretty advanced. If that were not so, I must say I would change to another engine now, and I don't mind paying for it either. Why? Because I am getting exceedingly frustrated when trying to use new functionality in Irrlicht.
My project basically uses the hardware initialization off irrlicht and the scenegraph. I add my own hardware buffers, because version 1.2 didnt have any as well as skeletal and morph animations and I just updated to 1.5 since I did not want to adjust my project to all the interface changes for every single update. I programmed all this stuff myself because frankly it was easier than to dig through the irrlicht sourcecode and figure out how animation and other nifty stuff worls

Now I'm trying to work a little more "compatible" by using Irrlicht objects where they exist instead of adding my own stuff but I am finding myself in the same pit. It's great that irrlicht now has feature x and function y, but how do I use it? The documentation frankly is not worth a cent, because it is merely mere than a funcitons and parameter list with spartanic comment. The tutorials that come with irrlicht have also run theor course, at least for me, because I learned all there is to learn from them in a few days some years ago.

Now I look at the functions in version 1.5 and find myself asking the question "how do I use this functionality?" I try to find usefull stuff in the howto section of this forum but its not too helpful when it comes to basic elements.

Instead of adding lots of new features in the next or overnext version, may I suggest writing a manual? It's great to have a free library, and I understand I will be faced with comments like "what do you expect it's free" but I for my part rather pay some money than to dig through tons of sourcecode. I develped library code that was used by other people myself and believe me, it's not too hard to add a few paragraphs to every function comment when you write it. It cost you 5 minutes at best and it would make irrlicht so much more useful

BlindSide · Post by **BlindSide** » Mon Mar 23, 2009 7:15 am

I guess the main reason it's lacking documentation is because the devs aren't too bothered if you come on here and ask how to do things personally.

Now we got that out of the way, what exactly were you having trouble with?

hybrid · Post by **hybrid** » Mon Mar 23, 2009 9:05 am

You're right that the Hardware mapping Hints did not get the best documentation so far. But good guess should lead you to IMesh.h where only a little part is not completely clear - which will guide you to the mapping hints and some more exaplanations in the enum.
Anyway, just tell us what would document these things better, and we'll happily add it to the 1.5.1 release already.

playerdark · Post by **playerdark** » Tue Mar 24, 2009 1:55 am

I'm more talking in general. when I make a class that others use, I usually write a class comment that explains the general usage of the class, it's relation to other classes, how other classes use it, what this class needs and so on.
Functions also get an extensive comment on what their general purpose is, why they are needed and in what kind of context they are used.

The biggest mistake library developers make is the "why document, it's all right there in the code" approach. A programmer in a company I worked for actually gave me that answer when I requested more comments. I'm happy that others do the work of dealing with the low level graphic stuff, don't get me wrong, as a games developer I don't want to mess around with DirectX or OpenGL, but I dont want to spend time chasing through the code in order to understand what the library can do for me and how I utilize that.

I'm not having specific questions, because chasing through the code is just what I'm doing right now so I'm getting there for my particular problems. I just wish I wouldn't have to do it. At least not for new features in the future, maybe if possible

Acki · Post by **Acki** » Tue Mar 24, 2009 3:36 am

this reminds me of something...

http://irrlicht.sourceforge.net/phpBB2/ ... hp?t=26248
http://irrlicht.sourceforge.net/phpBB2/ ... hp?t=27403

Nox · Post by **Nox** » Tue Mar 24, 2009 10:50 am

Well but how should somebody, who knows the source very well, guess where a newbody has problems and where not?

EDIT: and why dont you just correct the docu and submit it as a patch (as already mentioned)?

vipergc · Post by **vipergc** » Tue Mar 24, 2009 1:36 pm

I'd like to echo playerdarks sentiments regarding comments in the source code... As an old time programmer, I VERY much appreciate all the development effort that has been freely given to the IrrLicht project... and all of the time and effort that using the engine saves me.. I don't want to minimize my appreciation one bit...

that said... I also know that there are three very good reasons for adding ample comments when writing a routine..

1. the time cost is negligible

2. in 6 months, when you modify that routine, the little things
that you had floating around in your head when you wrote it,
are there in plain sight... this adds immeasurably to the
robustness of revisions and maintenance

3. it gives some insight to someone using the module as to
how to use it effectively, which directly translates to the engines
popularity with programmers and thus implementation

When I write routines and the associated comments, I try to keep in mind that first time reader, passing over to him what I know at the time so that he can easily get up to speed.

Again, thank you for a fine engine and all of the hard work that has gone into its development.

wITTus · Post by **wITTus** » Wed Mar 25, 2009 3:12 am

Maybe a bug report indicating very bad documented functions would help.

hybrid · Post by **hybrid** » Wed Mar 25, 2009 11:49 am

No, that wouldn't help much. But having some documentation fragments written by people who didn't wrote the code as well would help. Which is also a standard development technique, but just as the other ones mentioned by vipergc usually not applicable to OSS being developed in spare time. Especially point 1 does not fit here, because the development of Irrlicht can only be made if we devote 110% of our free time to programming and concepts. If we use more time then now on documentation (i.e. more than the doxygen docs for the API) it would halt the typical release cycles for far too long.
But hey, if the majority wants this - just start a vote where one can choose between Irrlicht 1.6 in summer 2010 or just the least API docs with at least one major release each year.

Brainsaw · Post by **Brainsaw** » Wed Mar 25, 2009 12:02 pm

I think the documentation is OK as it is. Of course it could be more complete and better, but hey ... just investing some time to dig into the doxygen docs, reading the tutorials and browsing the forums and wiki did help me with all questions I had until now. And if the problem wasen't solved that way I would do a post in the forum so that others can help me with my trouble. Just my 2 Cents.

Nox · Post by **Nox** » Wed Mar 25, 2009 12:22 pm

Well, how about sharing the experience to other? An admin can create a "how it works/docu" topic and everybody thinking that something is missing in the docu can write there a little note (maybe already in doxystyle). This way others dont need to test how something works and the notes can be easialy added to the docu. The dev teams have more time to spend for other things and other guys dont have to search to long.

Acki · Post by **Acki** » Wed Mar 25, 2009 2:33 pm

Nox wrote:An admin can create a "how it works/docu" topic and everybody thinking that something is missing in the docu can write there a little note (maybe already in doxystyle).

you mean something like this: http://irrlicht.sourceforge.net/phpBB2/ ... um.php?f=5 ???

Nox · Post by **Nox** » Wed Mar 25, 2009 3:23 pm

well i like funny people like you

is there a topic concerning missing documentation? Btw this is nothing for a faq. It should be a sticky topic for gathering the changes (for people who dont like the tracker

).

xDan · Post by **xDan** » Wed Mar 25, 2009 4:45 pm

it's a shame there isn't some way of exporting doxygen stuff as a wiki... is there?

Acki · Post by **Acki** » Wed Mar 25, 2009 4:57 pm

xDan wrote:it's a shame there isn't some way of exporting doxygen stuff as a wiki... is there?

well, not as wiki, but as general html: http://irrlicht.sourceforge.net/docu/index.html