Bullet wiki or documentation repo?

[Erwin Coumans]

Thanks for the tutorial link.

I got a lot of 'falling through the ground' with tri-meshes as ground and just balls

Are those small and fast moving balls? Are you using a large/variable timestep?

If you can reproduce it in a modified Bullet demo, it would be useful.
Thanks!
Erwin

[tea]

Thanks Erwin - maybe we should move this question to bugs/technical?

Are those small and fast moving balls? Are you using a large/variable timestep?
Erwin

- The balls are ~0.6 units (radius). They are moving at 0.0 to 2.0 units per second. Typically I setup with a ball at ~8 cm above ground level and it falls right through when the simulation starts, apparently under the influence of gravity ( 9.8 )
The ground : tri-mesh with 10-64 triangles, about 20x20 units. I mention non planar meshes because I used to have completely planar meshes and the problem usually doesn't show up at all in this case.
- fixed time-step (1/120 or 1/60).

I'll write a simple test or tweak a demo.

[Karrok]

Back on the topic of documenting.

Erwin, are the guidelines posted final?

If not, would it be an idea to have a hybrid documentation style? This would allow for a 3-fold documentation, each at a separate level.

headers -> general functionality and general usage
source -> in-depth documentation to supplement the documentation in headers. Describes in-depth functionality usage, algorithms and reasoning behind picking those.
demos -> example usage of the functionality

Obviously the demos are already made, although some additional comment might be good, as well as "cleaning" the demo's up, some of the demo's are hard to dig through if they have a particularly chaotic structure.

Having general (as far as general goes when commenting something as specific as a physics engine) comment in the headers should give enough information to easily start using the functionality, as well as keep the headers relatively clean.
The more in-depth comment in the source would serve two things. Firstly it should be explaining the innards of Bullet at a lower level, as well as perhaps algorithms used and reasoning behind the choices made. Secondly it would allow for people to understand choices/algorithms made/used and more easily suggest improvements, instead of being worn down by having to firstly find out what is actually happening in the first place.

My 2 cents

[VicariousEnt]

I agree mostly with the above. However, the more indepth stuff in the .cpp files should definitly be limited to info that people who are modifing or extending the bullet source would need. Also, this stuff should only be written by people on the dev team and in most cases the person who actually wrote the code as the rest of us will be just theorizing.

Any and all info that is important to the usuage of Bullet should strictly be in the headers. I consider documention to have failed in its purpose if I ever have to open a .cpp to figure out how to use an interface.

I would be happy to submit patches occasionally for headers that I have had to reverse engineer and have then successfully used. I would caution people with time on their hands who want to help out to just open up a header, scan through the cpp and start submitting documentation patches. Its like breaking the build in a development studio, don't commit unless you're sure your work is sound and has been tested. I would rather waste my time finding out how to use an undocumented interface then waste it debugging problems caused by misleading or wrong comments.

[Karrok]

I consider documention to have failed in its purpose if I ever have to open a .cpp to figure out how to use an interface.

Which is why the documentation in the headers should contain at the very least enough information to the user for him/her to be able to use it.

And the indepth documentation in the .cpp's would indeed be used to allow people to understand exactly what is going on and try improve on that. This does (in some cases) mean that it can get quite technical, including algorithms.
And sometimes the "why?" question can be important too. Why was algorithm A used instead of B (can be as short as "its faster").

But I think we're both thinking about similar things here

And yes ultimately a lot of the comment should still be coming from their creators. Especially for the non-trivial code it is hard, if not impossible to reverse engineer the documentation.
For the trivial parts (as far as trivial goes in a physics engine like Bullet), those confident enough in their knowledge of the functionality should be able to submit detailed documentation.

[Martin Felis]

In some other thread the discussion about documentation was started again. I will state the two most recent suggestions:

Maybe one can join the documentation efforts and knowledge gained by users/devs?

If anyone has added some Doxygen comments flying around, I'd be happy to add them to https://github.com/martinfelis/bulletphysics2.

Wouldn't it be better to supply the additional doxygen commented parts as patch suggestions to Erwin?

It should be fairly easy:

1. Get the SVN repo of Bullet (not the zip)
2. Make the comment/doxygen additions (trying to make them as extensive as might be needed)
3. Create an svn patch.
4. Post it under googlecode issue at: http://code.google.com/p/bullet/issues/detail?id=42

This way the documentation can take shape in a somewhat more organised fashion, and Erwin can check each submitted patch on correctness and completeness and make corrections if needed before it is commited to the main lead. I think this might be preferable to having a separate repo.

I agree with Karrok, that the steps he suggested would help. However I think sending patches to the googlecode issue would load more work on the developers with write access to the repository at googlecode. It would thus take some time until the documentation gets available to everyone (not counting downloading all documentation patches by hand).

Using something as github would have the advantage, that multiple people could start a community documentation and make their efforts public to others in a shared repository. As it is a distributed version control system, it is much easier to do all this (for a short introduction to dvcs: http://betterexplained.com/articles/int ... lustrated/). From this shared repository it should be easy to create patches that can be used by the official developers.

Furthermore, to me it seems as bullet might move over to github anyways (see https://github.com/erwincoumans).

I would be interesting how the main developers would like to receive improvements in the documentation.

(Concerning googlecode vs. github: I do not want to start any flame war. Instead I would like to keep discussions like that at bay as they are minor technical stuff anyways. I would rather want to use the efforts to 'just do' something about the documentation!)

[monkeyman]

One reason for source code comments (actually the biggest reason for my personal projects!) which I haven't seen mentioned much here is that if you are a productive programmer with lots of projects, you simply forget yourself why you wrote some code 12 months ago in one of hundreds of files you've written...

I always write exhaustive comments in my own projects, even if it means mentioning things that seemed trivial at the moment, because I *know* that I will waste time later figuring out if the internal parameter X was supposed to be positive or negative or if there are exceptions or limitations to some small algorithm used.

There is a lot of talk here about documenting the API, but for a skilled programmer starting to use Bullet, one very important thing is to get a feeling for the code itself and quickly get an intuitive feeling for where the designer knew what he was doing and where code is just a hack. The engine is not complete by any means, because the field is expanding all the time, so most of the time the user has to go into the code at some point anyway.

In Bullet, there is hardly any code analysis comments at all, and even the formatting of the code is off the map - I don't know what editor Erwin uses, but when I load it into emacs, I get horrible indentations and stuff like this: "void myfunction(int a, )" etc... anyway don't take that as criticism, just an observation - the Bullet library overall is incredibly cool to have as open-source! But it could easily be a LOT more programmer-friendly. It's not millions of lines of code - just taking 3-4 days just brain dumping all you know and come to think about while scanning through some of the most used .cpp files and adding comments could save several man-years in total programmer time afterwards!

So to summarize, the API-parts, doxygen generated documentation etc is good to fix but not the biggest issue I think. A physics engine is (currently) an incredibly complicated piece of algorithmic machinery, and I would not expect the parts to be perfect, so prioritizing actually helping programmers understand the code itself would help a lot in the long run, because it would generate more code-submissions in return, hopefully

[Martin Felis]

So to summarize, the API-parts, doxygen generated documentation etc is good to fix but not the biggest issue I think. A physics engine is (currently) an incredibly complicated piece of algorithmic machinery, and I would not expect the parts to be perfect, so prioritizing actually helping programmers understand the code itself would help a lot in the long run, because it would generate more code-submissions in return, hopefully

I think most of us agree that the code could use more commenting. And personally I don't have any preference where exactly it should be stored, however I do have a strong preference towards doing something about the documentation instead of discussing where to put it the Best Way Possible.

So to summarize, the API-parts, doxygen generated documentation etc is good to fix but not the biggest issue I think. A physics engine is (currently) an incredibly complicated piece of algorithmic machinery, and I would not expect the parts to be perfect, so prioritizing actually helping programmers understand the code itself would help a lot in the long run, because it would generate more code-submissions in return, hopefully

I did exactly that for the btKinematicCharacterController. You can have a look at it at https://github.com/martinfelis/bulletphysics2. If you have made any documentation efforts yourself I would be happy to add them.

Cheers,
Martin