Javadoc Comments

Engines, Libraries and Tools Xith3D Forums
#1

Just thinking that current Xith3D javadoc comments aren’t as good as they could be, most of them are only 1 or 2 lines long and I seem to find myself continuously looking @ the Java3D javadoc comments to get a more precise idea of what some classes/methods do.

I was just wondering if anyone had any thoughts on just how much rephrasing would have to be done (so as not to bring up any copyright/licensing issues and to make them specific to Xith3D) if some of the javadoc comments from Java3D were exported across into Xith3D?

#2

A very good question. Technically I believe (IANAL) that “rephrasing” is still violating their copyright. The ideal option would be to have someone with very good Java3D knowledge to write the comments using their knowledge of what they do but not refering to the Java3D ones.

I’ve been toying with the idea of trying to organise some Javadoc writing collaboration effort. We’ve got a lot of users now, if everyone fully javadoc’d say one class every week, it would not take long to have them all done. I have javadoc’d the classes where I did major work (i.e. the ASE loader) but it’s a very daunting task to do all of them by oneself.

What do you think?

Will.

#3

Yeah I think organising some kind of collaborative effort would be a very good idea assuming can get enough people. Count me in.

#4

You can put me down for a class.

#5

You’d need to be careful to get a consistant style and quality. One thing is worse that no documentation, wrong/bad documentation.

Kev

#6

I agree, we would have to have a very unambiguous guideline document before we start.

Anyone else interested? Maybe I should start a poll.

Will.