rtabmap_slam tests and doc (#1460)

* rtabmap_slam tests and doc

* another round of review of the doc

* Disable by default use_intra_process_comms on latched/transient publishers

* Added test to catch not unlocked mutex from early error exit

* updated coverage settings

* Using UScopeMutex on all tryLock()

.github/lcovrc

@@ -0,0 +1,45 @@
+# lcov configuration for .github/workflows/coverage.yml.
+#
+# A copy of colcon-lcov-result 0.5.0's default (colcon_lcov_result/verb/configuration/lcovrc),
+# with branch coverage turned off below. The whole file is needed: --lcov-config-file
+# replaces the default rather than adding to it.
+#
+# Why no branch coverage: gcc emits a hidden "it threw" branch on nearly every line that
+# calls a function, and no test takes it. Each such line -- a declaration like
+# 'rtabmap::Transform t;' included -- then counts as a partial, and Codecov reports a
+# partial line as not covered. lcov's geninfo_no_exception_branch would drop those
+# branches, but not with the lcov 1.15 of Ubuntu 22.04 and gcc 11: its JSON reader
+# ignores the flag, and its text reader cannot read gcc 11's .gcno files. So only line
+# coverage is reported: a line is covered when a test ran it.
+
+geninfo_auto_base=1
+
+# Specify size of tabs
+genhtml_num_spaces = 2
+
+# Include color legend in HTML output if non-zero
+genhtml_legend = 1
+
+# Include function coverage data display
+genhtml_function_coverage = 1
+
+# Include branch coverage data display
+genhtml_branch_coverage = 0
+
+# Specify whether to capture coverage data for external source
+# files
+geninfo_external = 0
+
+# Less verbose output
+lcov_quiet = 1
+
+# Specify if function coverage data should be collected and
+# processed.
+lcov_function_coverage = 1
+
+# Specify if branch coverage data should be collected and
+# processed.
+lcov_branch_coverage = 0
+
+## Follow symlinks
+lcov_follow = 1

.github/workflows/coverage.yml

@@ -60,7 +60,7 @@ jobs:
       # tested package depends on them (--packages-up-to), just not measured.
       - uses: ros-tooling/[email protected]
         with:
-          package-name: rtabmap_conversions rtabmap_util rtabmap_sync rtabmap_odom rtabmap_python
+          package-name: rtabmap_conversions rtabmap_util rtabmap_sync rtabmap_odom rtabmap_slam rtabmap_python
           target-ros2-distro: humble
           # RTAB-Map is installed in the image, not as an apt package, so rosdep
           # cannot resolve the key and must not try.
@@ -120,16 +120,18 @@ jobs:
           . /opt/ros/humble/setup.sh
           # C++ packages only -- rtabmap_python emits no .gcno for lcov to read,
           # and is measured by the coveragepy step below instead.
-          PKGS="rtabmap_conversions rtabmap_util rtabmap_sync rtabmap_odom"
+          PKGS="rtabmap_conversions rtabmap_util rtabmap_sync rtabmap_odom rtabmap_slam"
           # Baseline from the .gcno files. Without it a source file that no test
           # ever loaded is missing from the report altogether rather than
           # counted as 0%, which quietly inflates the result.
-          colcon lcov-result --initial --packages-select $PKGS
+          # Line coverage only, no branch coverage: see the comment in .github/lcovrc.
+          LCOVRC=src/rtabmap_ros/.github/lcovrc
+          colcon lcov-result --initial --packages-select $PKGS --lcov-config-file $LCOVRC
           # The verb ends by running genhtml and returns *its* exit code, so a
           # cosmetic HTML hiccup fails the whole job even though the report was
           # written. The deliverable is total_coverage.info; the HTML is a
           # convenience. Tolerate the former, then gate on the latter.
-          colcon lcov-result --packages-select $PKGS --verbose \
+          colcon lcov-result --packages-select $PKGS --lcov-config-file $LCOVRC --verbose \
             --filter '*/test/*' '/usr/*' '/opt/*' \
               '*CompilerId*' '*/CMakeFiles/*' || true
           test -s lcov/total_coverage.info

.github/workflows/ros2.yml

@@ -25,16 +25,16 @@ jobs:
         include:
         - ros_distro: humble
           skip_keys: ''
-          packages: 'rtabmap_ros rtabmap_conversions rtabmap_odom rtabmap_sync rtabmap_util rtabmap_python'
+          packages: 'rtabmap_ros rtabmap_conversions rtabmap_odom rtabmap_slam rtabmap_sync rtabmap_util rtabmap_python'
         - ros_distro: jazzy
           skip_keys: ''
-          packages: 'rtabmap_ros rtabmap_conversions rtabmap_odom rtabmap_sync rtabmap_util rtabmap_python'
+          packages: 'rtabmap_ros rtabmap_conversions rtabmap_odom rtabmap_slam rtabmap_sync rtabmap_util rtabmap_python'
         - ros_distro: kilted
           skip_keys: 'grid_map_ros'
-          packages: 'rtabmap_ros rtabmap_conversions rtabmap_odom rtabmap_sync rtabmap_util rtabmap_python'
+          packages: 'rtabmap_ros rtabmap_conversions rtabmap_odom rtabmap_slam rtabmap_sync rtabmap_util rtabmap_python'
         - ros_distro: lyrical
           skip_keys: 'velodyne grid_map_ros libpointmatcher'
-          packages: 'rtabmap_ros rtabmap_conversions rtabmap_odom rtabmap_sync rtabmap_util rtabmap_python'
+          packages: 'rtabmap_ros rtabmap_conversions rtabmap_odom rtabmap_slam rtabmap_sync rtabmap_util rtabmap_python'
         - ros_distro: rolling
           # Rolling has moved to Ubuntu resolute and much of it has not been rebuilt for
           # that yet, so rosdep finds nothing to install for these. They are all optional