Bullet wiki or documentation repo?

[Lil_Margin]

[update]
I made the tutorial as promised and it can be found in This topic

I hope you guys find it useful and at it to the wiki.

[jann.poppinga]

The search function seems to be broken. I just get "You have requested an invalid special page, a list of valid special pages may be found at Special:Specialpages", whether I search for "bullet" (http://www.bulletphysics.com/mediawiki- ... llet&go=Go) or "swine flu" (http://www.bulletphysics.com/mediawiki- ... +flu&go=Go).

[Erwin Coumans]

Thanks for the report. We had some server issues and move to a different server. Search should work fine now.

Thanks,
Erwin

[Erwin Coumans]

There is some interest in helping to improve the Bullet documentation.

We need set some guidelines, describe the different sources of documentation such as

• Doxygen comments in header files
• Wiki pages
• Bullet user manual, Presentations etc.
• Forum discussion topics
• Googlecode issue tracker, commits

possibly more, and how to cross-link between them.

We can keep the discussion about this in this topic, and send Doxygen header file comment patches in this Googlecode Issue 42.

Thanks,
Erwin

[ndujar]

Hi.

I am working on the doxygen documenting of bullet for my own purposes and I have thought it would be a good idea to share it others...so here I am...

I have done an initial approach to the subject. These are Erwin's comments from the google code project home:

1) Doxygen tags need to be used in the header files, not source. We need to pick what doxygen tags to
support etc.
2) Keep source code documentation very concise, avoid any duplication and redundant long sentences. If it is
about a derived method, only put the description in the base class, not in all derived classes. Doxygen should
pick this up. Also, documenting trivial methods (getNumConstraints -> get the number of constraints) needs
to be reviewed. I rather have an explanation of the abbreviations to avoid clutter (we use 'Num' for Number)
3) Don't add any 'discussion' being inserted in the source code, it belongs to a forum topic. At best, provide a
url of the forum and/or wiki page for further details
4) We need some guidelines to cross-link to different sources of documentation, using URLs etc
5) Requests for changes is different from documenting. We try to keep the Bullet 2.x API stable and try to avoid
API breaking changes whenever possible. They will be postponed until Bullet 3.x

And these are my comments:

1.- I totally agree with this statement. Besides, there are some classes and functions only defined and implemented in the header, which has the potential of leaving stuff undocumented..
2.- I think being concise is necessary, but in my opinion verbosity helps more than annoys, regarding disentangling a piece of code. Of course, this is arguable, but very often I have found the solution to a problem by reading again and again the same class definition of the documentation. Some things may be perfectly trivial for the programmer, not so much for those who come behind.
3.- It really will avoid clutter and keep the code clean.
4.- I think URLs should only be addressed to bullet's server (wiki). If they are references to papers external to it, it is risky, provided they change quite often.
5.- I can write down everything I find that is not consistent or coherent with the coding guidelines (http://docs.google.com/View?docid=dcphzzkx_939dpq9hrhc). I could put it anywhere...a topic in the forum as pointed in 3) seems a good place to me.

[LtJax]

Hi, I also have a few comments about this:

1) One thing that has worked quite well for me was to put the documentation for public and protected methods and types in the header file, while putting documentation for private things into the C++ file. That keeps the header files cleaner and you can clearly make out which functions are important to you. Comments for private functions are less important, but might be a help for people trying to follow, change and/or improve the implementation. Either way, I think it's a good idea to have 2 doxygen builds, one for users and one for developers. The user version would remove as much implementation detail as possible, e.g., private types and functions and structs defined exclusively in .cpp files.

2) I don't think documentation should be concise at all. On the contrary, I think it should be thorough and leave no or little room for speculation, especially in the public interface. Ideally, all the parameters are documented and there are implementation specific notes (for example expected performance). I agree that documenting trivial methods is not necessary, but I'd consider it for public methods. The different syntax coloring of the doxygen comments also gives nice visual cues when reading the source. Also, get methods can link to the appropriate set methods and have notes about performance (can you execute getNumConstraints in constant time, or is it linear in the number of constraints? - of course, constant is to be expected and should be left out, but linear should definitely be documented).
Also, I agree that redundant documentation is bad. In most cases, pulling the description from a base class should suffice. However, sometimes, such a case could require additional documentation, and that should not be forbidden. Doxygen also allows you to pull descriptions from any other method, so it should be possible to have very little redundancy.

As for other parts of the documentation, I think the doxygen should really be the main source for all things you need to know when using it. As such, most parts of the bullet manual could be pulled into it. However, the doxygen documentation should also be the most strictly reviewed docs. When code changes, it needs to be reviewed whether that breaks part of the documentation. Likewise, documentation changes should be checked.
The wiki could and should be the more relaxed documentation tool. "Hardened" API or algorithmic documentation from the wiki could be pulled into the source documentation. I'm not a big fan of putting examples into the doxygen, so I think they should be discussed in the wiki. The wiki can also house the more tutorial-like documentation and FAQs.
As a rule of thumb, I think it's a good idea to not link from the doxygen to anywhere else. The documentation should always be thorough enough so that is not necessary. So basically, when you need to link to something, instead pull it into the doxygen.
However, linking from the wiki into the hardened documentation is probably a good idea.

Regards,
Marius

[sparkprime]

I find OGRE has pretty excellent doxygen API documentation, and since I use both all the time, it brings Bullet's much weaker API documentation into sharp focus

Bullet has virtually no discussive documentation. Some classes are entirely undocumented. Most classes just have a few functions that have a few words of documentation, and the rest of the functions have none.

I still use a local build of the Bullet doxygen API all the time, but mainly in order to browse source code easily (like an IDE). The actual documentation is almost useless.

Compare these two analogous classes:

http://www.ogre3d.org/docs/api/html/cla ... nager.html
http://www.continuousphysics.com/Bullet ... World.html

[robagar]

Yup, agreed. Bullet is severely let down by it's lack of (inline) documentation. The class and variable naming is good so you can usually work things out by reading the code (apart from the softbody code, which is let down by lack of documentation and one letter variable names )

It's a shame, 'cos it's obviously a very sophisticated and well coded API. I really don't want to see Bullet die for the want of a bit of explanation.

I'm up for writing some doxygen comments as far as I'm able. So, who has commit access to the svn?

[sparkprime]

Bullet won't die, because there is no competition in the open source world

ODE is no-longer maintained, all of the others have restricted licenses.

[liangma]

I'm reading and analysis the source code (exclude soft body). I put some link to the wiki.
However, even I understand the code, it's a huge work to writing everything.
I have figure out the detailed control flow between different stage of pipeline. Currently, I try to figure out the final stage btSequentialImpulseConstraintSolver.

[Prompt]

The best ever documentation is also included with Qt SDK. Full documentation in source file else header files are huge and hard to read or find reference quickly. If you add quick doc in header is a lazy documentation... I believe put documentation in .h is a mistake it's better to put in headers block well comments with doxygen //@{ //@}

[dumbo2007]

Hi,

I recently figured out the Triangle Mesh and the Height Map demo(Terrain Demo) supplied with the SDK. I would like to contribute a tutorial that can perhaps be added to the wiki. I was especially impressed with the Hello World tutorial and I am making a similar one for triangle meshes and height maps.

Is such a tutorial already available ? I saw that lot of people struggle initially with these 2 classes for making terrains and are unable to find information on how to use them. I am also working on reading RAW file data and making terrains out of general grayscale images.

I think it would be really useful to have sample, well explained code for these things in the wiki.

Thanks.

[tea]

Hi there,

I'm writing a few tutorials, primarily for my own sake.
I normally write and publish sample code / tutorial style material as and when I start with a library. I find that there are things that 'experts' at something forget to explain because they become self obvious after a while.
So these tutorials won't benefit deep knowledge of bullet, and as such they're not a substitute for in-depth docs, not 'well formed', not comprehensive etc... and it is normal practice for me to refer sources inline, trying to keep attributions right.

I publish this on my blog (http://www.oogtech.org/content)

I think the 'hello world' tutorial on the wiki is great, the minor regret is I just can't figure how it links from the wiki doc root. The tutorials include code snippets and tests (backed by a test framework, that is) - most of which are based on the hello world source code.

So I would like to know if it's OK to redistribute/republish the hello world code or portions thereof, and if so, who should get credited for the original code?

When I'm done if somebody finds my stuff valuable I'll be happy to share it.

I'm covering the following:
- hello world (simplified, I don't have much to add on top of the existing one)
- setting up 'collision meshes'
- getting notified when collisions/contact occurs
- how to use motion states (very simple example, no rendering code is involved)
- ... (according to what I need for my project)

Aside I think I have finally done a decent job at setting up bullet as an iOS/XCode static library and the resulting proj could help some devs out there. But I don't know how to share it (other than linking it from my blog) and I think it could benefit a second opinion. Advice welcome.

Thanks - sorry for the long post, hope somebody can find the time to read it.

[sparkprime]

I'm 70% sure I wrote the wiki hello world page, and about 40% sure I wrote the code. Can't remember if I based it on something already written, though.

I wouldn't worry about attribution, personally. Bullet has a very liberal license anyway.

[tea]

Cheers - I'm done with my tutorials for now. I wish they were a lot better tho'. The articles are listed here:

http://www.oogtech.org/content/2011/09/07/bullet-notes/

I don't feel confident about two related areas [edited this as it seemed obscure] :
- tri-mesh (static, dynamic or kinematic); get a lot of 'falling through the ground' with tri-meshes as ground and just balls/simple primitives intended to rest on them / move at around 1 meter per second.
- same tends to occur with kinematic convex hulls (static ones feel a lot more reliable)
It's not a problem for our coming project so I won't have time to investigate right now - but it would be nice to have a really simple demo that shows how to setup a kinematic/static tri-mesh (like a simple, non planar platform) so that a ball can roll on it safely, or a box can sit on it without tunneling through (with btDiscreteDynamicsWorld)

I learned a lot from writing simple tests (looking like unit tests, but really just to find out what the library does) and I hope to publish this along with our Objective C integration when I find time...