API documentation

[osrf-migration]

Original report (archived issue) by Louise Poubel (Bitbucket: chapulina, GitHub: chapulina).

---

Summary

A lot of the API (most of it?) is not documented, so downstream developers need to come dig through the code to find out what functions are supposed to be doing.

For example, what does ConstructCollision do? Does it create and attach a collision to a link? How is that different from AttachMeshShape? If they do similar things, why are their names so different?

Motivation

It's difficult for downstream developers to use the API if it's not clear what it does.

Describe alternatives you've considered

Forcing everyone to dig through the code or test the API by trial and error? 😬

Additional context

Documentation is love 💟

[osrf-migration]

Original comment by Michael Grey (Bitbucket: mxgrey, GitHub: mxgrey).

---

Sorry for this situation. In my mind, the ign-physics API has been in a prototype phase this whole time, so I've been reluctant to dump time into documenting things when I don't know how permanent any of it is. There are still some major aspects of the API that I intend to iterate on when time permits.

But admittedly it's reached a point where it's too complicated to be used without documentation even by internal folks, so I'll put some time towards adding documentation as soon as I can.

[osrf-migration]

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

---

Thanks!

One approach we've taken in the past is to at least make sure to document all functions that are touched by pull requests. As things start being more documented, then the task of documenting the rest is a bit less overwhelming.

[osrf-migration]

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

---

This page is a nice reference of what classes are missing documentation. We could start the documentation effort by documenting all classes (without getting into their functions).

[claireyywang]

@anindex Since there is already an issue, I will just tag along here.

List of ign-physics classes that need documentation https://ignitionrobotics.org/api/physics/3.1/annotated.html
To add documentation to doxygen, click on the class name on the API page above to see the relavant source code file name.

• AttachBoxShapeFeature
• AttachCylinderShapeFeature
• AttachPlaneShapeFeature
• AttachSphereShapeFeature
• ConstructEmptyLinkFeature
• ConstructEmptyModelFeature
• ConstructEmptyWorldFeature
• GetBasicJointProperties
• GetBasicJointState
• GetEngineInfo
• GetJointFromModel
• GetLinkBoundingBox
• GetLinkFromModel
• GetModelBoundingBox
• GetModelFromWorld
• GetShapeBoundingBox
• GetShapeCollisionProperties
• GetShapeFrictionPyramidSlipCompliance
• GetShapeFromLink
• GetShapeKinematicProperties
• GetWorldFromEngine
• RemoveModelFromWorld
• SetBasicJointState
• SetCylinderShapeProperties
• SetFreeGroupWorldPose
• SetFreeGroupWorldVelocity
• SetJointVelocityCommandFeature
• SetShapeCollisionProperties
• SetShapeFrictionPyramidSlipCompliance

[claireyywang]

closing since all PRs are merged