next »

[cowwoc]

Hi,

What is the official roadmap for Xith3D? How often do you plan on releasing updates? When do you plan on releasing version 1.0? Which versions will contain API changes versus remaining backwards compatible?

I am reluctant to base a commercial product on top of Xith3D until I get a better understanding of where this is going. I have seen plenty of good scenegraph APIs gain large community support only to lose direction a few years later. Case in point: http://www.jmonkeyengine.com/jmeforum/index.php?topic=9247.0


Thank you,
Gili

[Marvin Fröhlich]

Hi cowwoc. Welcome to Xith3D .

Since Xith3D is made by hobbyists only, we cannot promise an update plan. The API is more or less fixed. There will only be API changes in the sound-part of the engine.

I would love to see, if you would base a commercial project on Xith3D. Please consider to contribute patches or new features to the project, if they are worth sharing. Of course I know, that you can't contribute anything, since you're creating a commercial product.

If you have any question concerning the API, the features, documentation or anything else, please don't hesitate to ask.

Marvin

[cowwoc]

I am worried by the fact that quite a bit of classes contain absolutely no Javadoc. Why don't you enforce a coding standard that all classes must be fully documented?

[hawkwind]

Better than javadoc is the vast number of test case applications.  Most of these exercise a small portion of the API which simplifies understanding how its used.

[Marvin Fröhlich]

I am worried by the fact that quite a bit of classes contain absolutely no Javadoc. Why don't you enforce a coding standard that all classes must be fully documented?

Hmm... I wouldn't say, that there are many classes, that don't contain any JavaDoc. Most of them have any especially the important ones do. Which classes are you referring to? Maybe I could document them.

We have a coding guideline, that tells to never commit a class without JavaDoc. But you should also take into account, where this project came from. It contained much less JavaDoc a few Years ago. And this guideline is only two years of age or so.

Marvin

[cowwoc]

Marvin,

Atlassian gives out free copies of their software for open-source projects. I highly recommend you apply for free copies of JIRA, Clover, Bamboo and maybe even Crucible. This will improve your bug tracking and also flag any class which is missing documentation. See http://www.atlassian.com/ for more information.

Take a look at org.xith3d.ui.hud.base.Border for example. It contains @return tags but it's totally missing method descriptions so when you look at the method listing you see absolutely no documentation. It might be "obvious" what each method does but it's a slippy slope. Take a look at org.xith3d.ui.hud.geometries.BorderGeom for example, no comments at all. I am just clicking on random class names here and it looks like quite a few of them are missing a substantial amount of comments.

Doesn't your IDE give you warnings about missing Javadoc? Mine does.

PS: IntelliJ IDEA also gives out free copies of their software for open-source projects in case this interests you. I happen to use Netbeans but I've heard very good things about that IDE.

If you need help getting the Atlassian stuff up and running I am more than willing to help you out.

Gili

[Mathias 'cylab' Henze]

Actually we wouldn't need more infrastructure, but more core devs. Tracking the bugs here in the forum is sufficient, I think. If you want to help, write some docs or attract/motivate more people to join xiths core development

[cowwoc]

Seriously? In my experience using anything other than an issue tracker is a disaster. Issues will "fall through the cracks" and you will forget about them. This includes bug fixes, new feature requests, ideas, etc. The issue tracker will even produce changelogs for you automatically. Anyway, just my 2 cents. You guys can get all these great tools for free (they normally cost thousands a year) so why not give them a try?

[Marvin Fröhlich]

Atlassian gives out free copies of their software for open-source projects. I highly recommend you apply for free copies of JIRA, Clover, Bamboo and maybe even Crucible. This will improve your bug tracking and also flag any class which is missing documentation. See http://www.atlassian.com/ for more information.

Mathias said it. This board is sufficient for tracking bugs. If there is a bug, that I can't fix right away, I move the specific topic to the special bugs forum, to remember me about it. I like to have everything at one place. And this forum is that place .

Take a look at org.xith3d.ui.hud.base.Border for example. It contains @return tags but it's totally missing method descriptions so when you look at the method listing you see absolutely no documentation. It might be "obvious" what each method does but it's a slippy slope.

Indeed, the Border.Description methods don't have documentation. I will add it when I have time. On the other hand these methods are indeed very obvious about their functionality.

My IDE doesn't warn me about missing Javadocs. But I could configure it to do so. Maybe I should. If a method isn't more than a simple getter, it doesn't need more documentation than the @return tag. If I would add a method description, it would be a duplication of the @return tag value. And this would be ugly. My IDE displays the value of the @return tag just fine. And in a HTML exported JavaDoc there would also be the @return tag. Where do you miss this documentation?

Take a look at org.xith3d.ui.hud.geometries.BorderGeom for example, no comments at all.

This class is not for public use. So comments are less important. But of course it should still have more than just the class documentation.

I am just clicking on random class names here and it looks like quite a few of them are missing a substantial amount of comments.

For me it looks like you're expecting something else from the JavaDoc than I am. As I said, @return tags are sufficient, if the method doesn't do more than returning a value.

PS: IntelliJ IDEA also gives out free copies of their software for open-source projects in case this interests you. I happen to use Netbeans but I've heard very good things about that IDE.

No, I am not . I use Eclipse and I am very happy with it.

Marvin

[Mathias 'cylab' Henze]

For me it looks like you're expecting something else from the JavaDoc than I am. As I said, @return tags are sufficient, if the method doesn't do more than returning a value.

Despite you are right about the methods only return some values, I see the point that having only @return tags would generate empty comments in the method overview. So if we stumple upon those case, it wouldn't hurt to copy the @return description up more or less one-to-one.

You guys can get all these great tools for free (they normally cost thousands a year) so why not give them a try?

I use all these great tools at work for more than 8 years now. I can assure you, that the tools don't do the work, people do If you are keen on managing aspects of xith development with these tools, we would probably be happy to let you do it. But we would require you to constantly dedicate your workforce and time to keep them up to date, review their contents, help people with using them and a lot of other project management tasks involved. Are you up to it?

It's the way it is now, because it needs minimal attention and doesn't get in the way. We only need to look into the forum and see what's up and what's not.

[cowwoc]

My IDE doesn't warn me about missing Javadocs. But I could configure it to do so. Maybe I should. If a method isn't more than a simple getter, it doesn't need more documentation than the @return tag. If I would add a method description, it would be a duplication of the @return tag value. And this would be ugly. My IDE displays the value of the @return tag just fine. And in a HTML exported JavaDoc there would also be the @return tag. Where do you miss this documentation?

If you using an IDE Javadoc browser then it is sufficient, but if you're viewing the online HTML documentation then each method needs to contain a brief description -- even if it's identical to the contents of @return tag -- for the sake of the "Method Summary" section. I've seen some Xith classes with methods such as getLLC(). Granted, that's just a getter but I have no clue what LLC means.

I agree that duplicating the @return text sucks, but it should still be done. The original source-code comments are not what matters, the rendered result *is*. The same can be said for Javadoc comments that contain HTML (the Java core APIs are full of this!). If you look at the comments in the source-code they are hard to read, but when you look at the resulting HTML output it is absolutely great and that's what matters. Just my 2 cents

PS: I wouldn't be surprised if there was a way to avoid this duplication. I haven't look into it.

[cowwoc]

I remain a bit skeptical of tracking bugs using the forum, but I guess I'll have to take your word for it What is the average turn-around time between a bug being reported and getting fixed? Does anyone offer commercial support for Xith3D in case we run into problems (or find a bug) and need a quick resolution?

Thank you,
Gili

[Marvin Fröhlich]

If you using an IDE Javadoc browser then it is sufficient, but if you're viewing the online HTML documentation then each method needs to contain a brief description -- even if it's identical to the contents of @return tag -- for the sake of the "Method Summary" section. I've seen some Xith classes with methods such as getLLC(). Granted, that's just a getter but I have no clue what LLC means.

I've checked the online JavaDoc and you're right. There should be brief method descriptions even for getters.

PS: I wouldn't be surprised if there was a way to avoid this duplication. I haven't look into it.

This would be very useful. Please report back, if you find anything about it.

I agree that duplicating the @return text sucks, but it should still be done. The original source-code comments are not what matters, the rendered result *is*. The same can be said for Javadoc comments that contain HTML (the Java core APIs are full of this!). If you look at the comments in the source-code they are hard to read, but when you look at the resulting HTML output it is absolutely great and that's what matters. Just my 2 cents

I personally perfer it the other way round. I never look into the online JavaDoc, since it is very uncomfortable to use while IDE internal JavaDoc is very easy to use and is accessed in no time. If you checkout the SVN trunk and bind the project to yours, you can even jump into the methods and read the code for even more information. But I do agree, that both IDE and HTML JavaDoc should be good. I will try to improve it when I have time (it's on my list).

I remain a bit skeptical of tracking bugs using the forum, but I guess I'll have to take your word for it What is the average turn-around time between a bug being reported and getting fixed?

It depends on how much time I/we have. If I have plenty of spare time, I usually fix reported bugs very shortly (sometimes within minutes). But this is still a project developed in free time. So nobody can guarantee you, to have the necessary amount of spare time. Just browse these forums and you will see, that very most bugs have been fixed within a very short time.

Does anyone offer commercial support for Xith3D in case we run into problems (or find a bug) and need a quick resolution?

AFAIK this has never been done before. But we can make an appropriate arrangement, it is not impossible.

I strongly encourage you to do some first steps using the engine. You will see, that it is very easy to use. Also read the main documentation XIN as well as the InputSystem's documentation.

Marvin

[Marvin Fröhlich]

What would you say, if I just convert JavaDocs like this:

Code:

/**
 * @return foo something bar.
 */

to

Code:

/**
 * Returns foo something bar.
 */

?

Would this suit your needs?

Marvin

[cowwoc]

What would you say, if I just convert JavaDocs like this:

Code:

/**
 * @return foo something bar.
 */

to

Code:

/**
 * Returns foo something bar.
 */

?

Would this suit your needs?

Marvin

Personally I would say it should be:

Code:

/**
 * Returns foo something bar.
 *
 * @return foo something bar
 */

I tend to discuss exceptional cases in @return if I can, otherwise I duplicate the first sentence of the description. Here is an example of an exceptional case:

Code:

/**
 * Returns the preferred size.
 *
 * @return null if the preferred size is not set
 */

Like all other documentation, it's easier to add it as you go along. And remember, you write the documentation once, but it'll get read hundreds of times, so it's worth getting it right... Just my 2 cents

Gili