Bullet wiki or documentation repo?
-
- Posts: 10
- Joined: Sun Jul 19, 2009 5:24 am
Re: Bullet wiki or documentation repo?
[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.
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.
-
- Posts: 12
- Joined: Wed Aug 26, 2009 3:32 pm
Re: Bullet wiki or documentation repo?
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).
-
- Site Admin
- Posts: 4221
- Joined: Sun Jun 26, 2005 6:43 pm
- Location: California, USA
Re: Bullet wiki or documentation repo?
Thanks for the report. We had some server issues and move to a different server. Search should work fine now.
Thanks,
Erwin
Thanks,
Erwin
-
- Site Admin
- Posts: 4221
- Joined: Sun Jun 26, 2005 6:43 pm
- Location: California, USA
Re: Bullet wiki or documentation repo?
There is some interest in helping to improve the Bullet documentation.
We need set some guidelines, describe the different sources of documentation such as
We can keep the discussion about this in this topic, and send Doxygen header file comment patches in this Googlecode Issue 42.
Thanks,
Erwin
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
We can keep the discussion about this in this topic, and send Doxygen header file comment patches in this Googlecode Issue 42.
Thanks,
Erwin
-
- Posts: 7
- Joined: Fri Apr 02, 2010 4:31 am
- Location: Spain
Re: Bullet wiki or documentation repo?
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.- 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.
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:
And these are my comments: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
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.
-
- Posts: 8
- Joined: Thu Sep 18, 2008 2:37 pm
Re: Bullet wiki or documentation repo?
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
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
-
- Posts: 508
- Joined: Fri May 30, 2008 2:51 am
- Location: Ossining, New York
Re: Bullet wiki or documentation repo?
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
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
-
- Posts: 48
- Joined: Fri May 21, 2010 1:49 am
Re: Bullet wiki or documentation repo?
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?
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?
-
- Posts: 508
- Joined: Fri May 30, 2008 2:51 am
- Location: Ossining, New York
Re: Bullet wiki or documentation repo?
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.
ODE is no-longer maintained, all of the others have restricted licenses.
-
- Posts: 4
- Joined: Wed Feb 18, 2009 6:33 pm
Re: Bullet wiki or documentation repo?
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.
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.
-
- Posts: 13
- Joined: Wed Jul 28, 2010 9:31 pm
Re: Bullet wiki or documentation repo?
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 //@{ //@}
-
- Posts: 66
- Joined: Sun Jan 30, 2011 8:46 pm
Re: Bullet wiki or documentation repo?
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.
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.
-
- Posts: 6
- Joined: Mon Jul 18, 2011 6:42 pm
Re: Bullet wiki or documentation repo?
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.
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.
-
- Posts: 508
- Joined: Fri May 30, 2008 2:51 am
- Location: Ossining, New York
Re: Bullet wiki or documentation repo?
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.
I wouldn't worry about attribution, personally. Bullet has a very liberal license anyway.
-
- Posts: 6
- Joined: Mon Jul 18, 2011 6:42 pm
Re: Bullet wiki or documentation repo?
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...
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...
Last edited by tea on Wed Sep 07, 2011 7:42 pm, edited 1 time in total.