[EMAIL PROTECTED] wrote:
>> From: Marcus Lindblom
>> Hi Toni,
>>
>> I agree that important classes (i.e. 'Node') and exceptional cases
>> should be documented. But as long as we are mostly developers, my
>> opinion is that adding fine-grit documentation is something of a waste
>> of good development time.
>
> Developers of OpenSG, or developers of software that uses OpenSG? If
> the former, fine, but if the latter... how is anyone supposed to learn
> the system?
Well, I managed to learn it and develop something pretty close to a
useable product from it in about 6 months during last year. But ok, I
had help from the mail-list, have known OpenGL pretty well for 7 years
now and OpenSG is quite similar to how I would engineer things, so I
suppose I'm a bit biased. :)
I really liked Dirk's small docs on chunks or various classes. However,
that info could also have been put in the class's documentation.
Lately, I look more and more into the source code of OpenSG to
understand how things work, but you'd probably have to be pretty
experienced (i.e. +1 year) to do that. I suppose good all around docs
would ease the way for beginners.
One thing with Doxygen today is that many classes contain duplicate
info, the stylesheet is quite 'spacey' and thus it is hard to scroll
down. Ideally, making two separate docs (one for users, one for
developers) would be nice, to make user docs more relevant, but the
build times for doxygen are indeed quite horrible.
>> For NodePtr getChild(index), it's pretty obvious that you get a null ptr
>> if the index is out of range, since that is common engineering practise.
>> (If getChild returned a reference, then you'd need some documentation
>> saying if an exception gets thrown or whatever.)
>
> Is it obvious though? For a new user to OpenSG, there's a very real
> chance of checking the returned pointer against NULL, not NullFC...
Well, NullFC has practically been abolished now, since any Ptr can be
implicitly converted to something boolean and tested on, i.e:
if(NodePtr x = y->getChild(42)) { x->foo(); } is perfectly valid. (or
just if (x) { x->foo() } ).
Anyway.. this is just details.
> It's also worth mentioning that there are also inconsistencies in the
> documentation that does exist!
This is what I was getting at with updating docs. It's not easy to keep
docs updated if you are collaborating or fixing bugs afterward. But as
Toni has said, given a little discipline and change of thought, it ought
to be possible to improve things a lot.
>> Documenting everything, while being a honorable goal and useful for
>> adopting people fast, takes a lot of time to do,
>
> Agreed, a very long time. But it's the one thing that makes writing
> code that uses APIs an enjoyable task. I don't enjoy coding pain.
Me neither.
Anyway, I'm probably not the best person to comment on this, as I can't
really remember my early days of OpenSG coding.
/Marcus
-------------------------------------------------------------------------
Using Tomcat but need to do more? Need to support web services, security?
Get stuff done quickly with pre-integrated technology to make your job easier
Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo
http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642
_______________________________________________
Opensg-users mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/opensg-users
