Effort to improve the Xith3D API documentation

Engines, Libraries and Tools Xith3D Forums
#1

The Xith3d javadocs need a lot of work. As it is a huge task, I’m trying to get an idea of who will be able to help.

How I believe we could do it is if we had say 20 or 30 people who took a couple of .java files each week and fully javadoc’d them.

The goal would be to have complete javadoc’s for the whole API (that’s all methods, parameters, returns, classes, exceptions, etc. documented) PLUS all unimplemented methods marked as such (perhaps using a custom @unimplemented tag or something). Thus, once complete we would hopefully be able to program with Xith3d without looking at the source code.

No actual code changes would be accepted as it would be too confusing - although these patches could be submitted separately.

This would be a good chance of giving something back to the Xith3D community while doing something which is of a direct benefit to yourself and others.

Will.

PS. If you vote “yes”, please also reply to this topic so we know who you are :slight_smile:

PPS. This poll is continuing the thoughts raised in this thread

#2

+1

#3

I said “yes” but I won’t be writing anything.

What I can do is review them. This is an essential stage, especially if you’re having more than 2 or 3 people writing docs, and even more so if they’re not being written by xith3d core authors :).

I do use Xith a bit, but not enough to want to write docs (nor do I have the time to think that much), but enough that I can read someone else’s docs and quickly point out which comments aren’t good enough and why.

e.g. recognising where a method comment doesn’t actually describe the method, but instead just rephrases the words used in the method name :).

#4

that would be very helpful. Thanks.

Will.

#5

I’ll help out with this (assuming I’m ever gonna get a chance to touch a computer outside work). Would like to see that guideline up front tho.

Kev

#6

+1 also

#7

4 people so far (including myself) + 1 to review.

Anyone else want to help out? It’s not a huge amount of work, just documenting a couple of class files when you have the time.

Will.

#8

Hi

Can do a bit.

Bye Adi

#9

Ok,

Time to do my bit…
I’d be happy to document a few classes

#10

+1
Maybe yes, if I find the time to do it !

It’s sure that the documentation is’nt complete at all !
For exemple : how should I detect collision between two geometry objects ?

#11

[quote]+1
Maybe yes, if I find the time to do it !

It’s sure that the documentation is’nt complete at all !
For exemple : how should I detect collision between two geometry objects ?
[/quote]
Uh yea… I just realized that there is no explicit support of collision detection or avoidance in the “Xith3D Features” thread… I guess you have to do that yourself?

Okay nevermind, I just looked in the Javadoc and there are a bunch of classes to support collisions – must have just been left out of the Features thread accidentally.

#12

The collision stuff is not part of the core despite that fact it may appear so. Xith3D is a scenegraph first and foremost. Make sure you search the threads here for info on that package some people have reported problems. You are free to use whatever collision code you like :slight_smile:

Will.

#13

So I will use OdeJava for my collision detection.