> And simple methods like
>
> NodePtr osg::Node::getChild( UInt32 childIndex )
>
> need a proper documentation! I mean, I don't expect that you tell me
> what childIndex means, but I want to know what is returned if I give
> you an inexistent childIndex.
ah, that's exactly what i meant!
>
> I agree though that set/get methods which set and return a member
> variable don't necessarily need a documentation.
sure -- provided that member variable is documented ... ;-)
> You can write: "Adds 'child' as child of this Node, if
> child is Null blabla... else blabla, returns true on success,
> otherwise returns false".
exactly -- and that would not reduce productivity that much.
> "
> bool QImage::isNull () const
> Returns true if it is a null image, otherwise returns false.
> A null image has all parameters set to zero and no allocated data.
notice the second sentence!
> You can either like it or not, I personally like it. There's a
and it's always better to have one method documented that would not
really *need* to be, than to have a method undocumented that would
really need some doc.
> The doc does not have to be up to date in real time I think, so you
> might consider generating it just once a week or so.
>
you could even set up a little cron job to do it overnight ...
> IMHO this is one of the example where the description is not
> necessary. I mean
> the height of an image object is somehow self-explanatory.
hm, not necessarily: is the height in pixels or in mm? what height do
i get for an empty image? 0 or -1?
again, it's the description of the unusual cases that are the really
helpful part and let a documentation shine.
> used it before, i simply go to the "Model/View Programming" page
> available on
> the documentations main page under section "Key technologies" and
> after
> reading that i know about:
>
> - the model/view concept (even if i never header of that before)
> - the classes involved
> - the relations between the involved classes
> - several (documented) examples
ok, that's the high-level documentation.
i'm not sure that that's something that can be expected from
developers, i think that would best be done by a technical writer ...
But i agree: in order to get started with a non-trivial feature, this
would be needed.
> executable that does not need perl, but that failed so far. Not
> knowing
> python very well, is there any option like this available ?
yes, you can create executables from python source code.
> For NodePtr getChild(index), it's pretty obvious that you get a
> null ptr
no it's not; at best, it's relatively likely, but there are several
other options, that are not unlikely as well, for instance, it could
throw an exception, or return a null object.
> Unless someone is willing to do it, or willing to pay some one else to
> do it, I think all that is needed is to put a little something on
> every
> class and try to document non-obvious things. That would give us much
but that's exactly the point: exactly what is and what is not obvious
is very different depending on who you ask, the developers or a
newbie. That's why i recommend to document even the "obvious" stuff.
Best regards,
Gabriel.
_________________________________________________________________
If you know exactly what you will do --
why would you want to do it?
(Picasso)
_________________________________________________________________
-------------------------------------------------------------------------
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
