Expand Documentation Explaining Design and Usage of Gazebo

[osrf-migration]

Original report (archived issue) by Andrew Hundt (Bitbucket: ahundt).

---

An improvement that would be extremely helpful and smooth out the process for new users would be more documentation of the overall design concepts and usage of gazebo. The overall design of gazebo is quite good, which means a lot can be accomplished by improving how that design is communicated to users.

Edit: I've found the User Guide, but it is out of date (1.9) and should be linked to in the "Get your feet wet" section of the Getting Started section of the gazebosim.org front page.

For example, while there was a genuine bug in issue #1127, one source of confusion was figuring out how visual strings are modified.

Specific points of confusion:

1. How to access SDF elements in C++
   • I had to look through the code to discover that simply using link names would fail
2. Interaction of model class names, registered names, shared library filenames and what the constraints of those elements are.

What could be added:

1. Dictionary - explain specific terms, and in what contexts they can be used

   • visual example:
     • Applies to modules: SDF, Rendering, Physics
     • A visual element can be identified by either a unique string and/or integer identifier
     • The name string of a visual element in the SDF file is not the same name as the visual identifer string in C++ code. Instead, the C++ visual identifier string is composed from the scope of the visual identifier and its parents element. For example if you have a model "modelname" that contains a link "linkname" which contains a visual "visualname", the model unique identifier is "modelname" the link unique identifier is "modelname::linkname", and the visual unique identifier is "modelname::linkname::visualname".
     • The visual element interacts with the rendering scene and can be used to extract information about the scene and ground truth data about how sensors are interacting with the simulation.
       • Other related functions and components you may want to see include: class1 class2, function1, ...
       • Additional terms that need to be identified and have their interaction with other components explained:
       • Scene, Model, link, plugin, script, event, collision, actor, model, factory, node (including both transport and scene graph contexts), etc...

2. Explanation of API functions and cross referencing could make it easier to understand and use components. Some of the API documentation is a restatement of the function names at the moment.

   • Taking the "visual" example above, I did search the wiki for "visual" and was brought to this page: http://gazebosim.org/wiki/Interfaces . This would likely be a good spot to put some additional details explaining what these elements are.
   • Here is an example demonstrating how the function description is a restatement of the function name itself: http://gazebosim.org/api/dev/classgazebo_1_1rendering_1_1Scene.html#a8dc996b50f1ed9585f845738b94fdfcc
     • Ideally the keyword visual could be turned into a link or use one of the inline doxygen reference definitions to the definition of what exactly constitutes a visual string. This would mean less writing but still allow people to find the information quickly. Also, a short description of why you would want to use it would be helpful.
   • A good example library documentation is the boost.geometry library.
     • Overall library: boost.org/libs/geometry
     • Example function: http://www.boost.org/doc/libs/1_55_0/libs/geometry/doc/html/geometry/reference/access/get/get_1.html

3. Clear and easy ways to debug and diagnose and resolve problems with loading plugins, including printing the set of paths that were searched and warning of duplicate library names on the path.

4. Error messages explaining or guessing what may be wrong with an SDF file, plus instructions on how to fix it, or where to find said instructions.

[osrf-migration]

Original comment by Andrew Hundt (Bitbucket: ahundt).

---

• Edited issue description

[osrf-migration]

Original comment by Andrew Hundt (Bitbucket: ahundt).

---

• changed title from "Documentation Explaining Design and Usage of Gazebo" to "Expand Documentation Explaining Design and Usage of Gazebo"

[osrf-migration]

Original comment by Andrew Hundt (Bitbucket: ahundt).

---

• changed kind from "bug" to "proposal"

[osrf-migration]

Original comment by Andrew Hundt (Bitbucket: ahundt).

---

• Edited issue description

[osrf-migration]

Original comment by Nate Koenig (Bitbucket: Nathan Koenig).

---

Thanks for the feedback. I'll look into incorporating your ideas into our resources.

[osrf-migration]

Original comment by Nate Koenig (Bitbucket: Nathan Koenig).

---

• set assignee_account_id to "557058:095b1e12-74ed-4e20-b44f-2f0745b616e0"
• set assignee to "nkoenig (Bitbucket: nkoenig, GitHub: nkoenig)"

[osrf-migration]

Original comment by Steve Peters (Bitbucket: Steven Peters, GitHub: scpeters).

---

• set component to "documentation"

[osrf-migration]

Original comment by Louise Poubel (Bitbucket: chapulina, GitHub: chapulina).

---

@spaepcke

[osrf-migration]

Original comment by Steffi Paepcke (Bitbucket: spaepcke).

---

Thanks, Louise. @caguero and @j-rivero this will be useful for the FTD and FTC personas.

[osrf-migration]

Original comment by Nate Koenig (Bitbucket: Nathan Koenig).

---

• set version to "all"