Documentation, Style and scripting interfaces update

[osrf-migration]

Original report (archived issue) by Nate Koenig (Bitbucket: Nathan Koenig).

---

Summary

The documentation, code style, and scripting interfaces in this library needs to be updated. This issue will track progress.

Work to be done

For each class:

1. Create an example in the examples folder. This example should then be used as a doxygen \snippet in the class's doxygen description.

2. Check spelling.

3. Check for code style. Set functions should start with Set. Don't use const with POD types. Etc.

4. Create a scripting interface. See Angle.i as an example.

5. Add more tests so that coverage is as close to 100% as possible.

6. Target changes to ign-math6. Also, target main with any breaking changes.

Status

1. Angle. See pull request #325 and pull request #326. Basic setup for Python interface using SWIG #216
2. AxisAlignedBox AxisAlignedBox Python interface #262 AxisAlignedBox: deprecate unimplemented methods #261
3. Box Box Python interfaces #273
4. Color Adds python interface to RollingMean, Color and Spline #218
5. Cylinder Cylinder Python interface #274
6. DiffDriveOdometry DiffDriveOdometry Python interface #265
7. Filter Adds python interface to Filter, MovingWindowFilter, RotationSpline. #230
8. Frustum Frustrum Python interface #278
9. GaussMarkovProcess Basic setup for Python interface using SWIG #216
10. graph/Edge
11. graph/GraphAlgorithms
12. graph/Graph
13. graph/Vertex
14. Helpers Fixed Helpers Python templates #266
15. Inertial Inertial Python interface #275
16. Kmeans Adds python interface for Kmeans and Vector3Stats  #232
17. Line2 Adds Line2, Line3, SignalStats, Temperature python interface #220
18. Line3 Adds Line2, Line3, SignalStats, Temperature python interface #220
19. MassMatrix3 MassMatrix3 Python interface #260
20. Material Adds python interface to MaterialType and Material. #234
21. MaterialType Adds python interface to MaterialType and Material. #234
22. Matrix3. See pull request #328 Adds python interface to Quaternion, Pose3, Matrix3 and Matrix4 #221
23. Matrix4 Adds python interface to Quaternion, Pose3, Matrix3 and Matrix4 #221
24. MovingWindowFilter Adds python interface to Filter, MovingWindowFilter, RotationSpline. #230
25. OrientedBox OrientedBox Python interface #276
26. PID Adds python interface to PID and SemanticVersion. #229
27. Plane Plane Python interfaces #272
28. Pose3. See pull request #329. Adds python interface to Quaternion, Pose3, Matrix3 and Matrix4 #221
29. Quaternion. See pull request #327. Adds python interface to Quaternion, Pose3, Matrix3 and Matrix4 #221
30. Rand Basic setup for Python interface using SWIG #216
31. RollingMean Adds python interface to RollingMean, Color and Spline #218
32. RotationSpline Adds python interface to Filter, MovingWindowFilter, RotationSpline. #230
33. SemanticVersion Adds python interface to PID and SemanticVersion. #229
34. SignalStats Adds Line2, Line3, SignalStats, Temperature python interface #220
35. Sphere Sphere Python interface #277
36. SphericalCoordiantes SphericalCoordinates Python interface #263
37. Spline Adds python interface to RollingMean, Color and Spline #218
38. Stopwatch Added StopWatch Python Interface #264
39. Temperature. See pull request #339. Adds Line2, Line3, SignalStats, Temperature python interface #220
40. Triangle3 Add Python interface to Triangle3 #247
41. Triangle Adds python interface to triangle. #231
42. Vector2 Basic setup for Python interface using SWIG #216
43. Vector3 Basic setup for Python interface using SWIG #216
44. Vector3Stats Adds python interface for Kmeans and Vector3Stats  #232
45. Vector4 Basic setup for Python interface using SWIG #216

[osrf-migration]

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

---

• Edited issue description

[osrf-migration]

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

---

• Edited issue description

[osrf-migration]

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

---

• Edited issue description

[osrf-migration]

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

---

• Edited issue description

[scpeters]

we should consider providing conversion functions between our ignition math vector and matrix types and numpy arrays.

[francocipollone]

• Basic setup for Python interface using SWIG #216 - Sets up SWIG to create bindings to python and create python examples and tests for all the classes that already have a SWIG interface (used for ruby)
• After the previous is merged, PRs will be adding a swig interface to the remaining classes only for python. (+test)

[WagnerMarcos]

At the moment, the python interface we are generating is providing the access to the classes methods using the Cpp name convention (e.g. in python you would use Temperature.CelsiusToKelvin(temp) to invoke the method). This could be modified, seemingly with little effort, using the %rename(celsius_to_kelvin) CelsiusToKelvin; SWIG directive in the interface file to get an interface with the PEP8 name convention as used in ROS2.

Would this be a better approach? Or would it be better to leave it matching the Cpp name convention?

[francocipollone]

At the moment, the python interface we are generating is providing the access to the classes methods using the Cpp name convention (e.g. in python you would use Temperature.CelsiusToKelvin(temp) to invoke the method). This could be modified, seemingly with little effort, using the %rename(celsius_to_kelvin) CelsiusToKelvin; SWIG directive in the interface file to get an interface with the PEP8 name convention as used in ROS2.

Would this be a better approach? Or would it be better to leave it matching the Cpp name convention?

As discussed during the weekly meeting if this isn't much effort we should match ROS2/PEP8 convention.

[chapulina]

This issue is mixing a lot of different things. I've broken it into new issues:

Create an example in the examples folder. This example should then be used as a doxygen \snippet in the class's doxygen description.

• Create examples for all classes #300

Check spelling.

• Improve all API documentation #303

Check for code style. Set functions should start with Set. Don't use const with POD types. Etc.

• Make API consistent #301

Create a scripting interface. See Angle.i as an example.

• Add Ruby interfaces to all classes #302

Add more tests so that coverage is as close to 100% as possible.

Coverage is already 100%