Module documentation: switch to Markdown

src/drivers/px4fmu/fmu.cpp

@@ -3493,11 +3493,13 @@ int PX4FMU::print_usage(const char *reason)
 
 	PRINT_MODULE_DESCRIPTION(
 		R"DESCR_STR(
-This module is responsible for driving the output and reading the input pins for boards without a separate IO chip
-(eg. Pixracer). On boards with an IO chip, the px4io driver is used.
+### Description
+This module is responsible for driving the output and reading the input pins. For boards without a separate IO chip
+(eg. Pixracer), it uses the main channels. On boards with an IO chip (eg. Pixhawk), it uses the AUX channels, and the
+px4io driver is used for main ones.
 
 It listens on the actuator_controls topics, does the mixing and writes the PWM outputs.
-In addition it does the RC input parsing and auto-select the method. Supported methods are:
+In addition it does the RC input parsing and auto-selecting the method. Supported methods are:
 - PPM
 - SBUS
 - DSM
@@ -3508,17 +3510,25 @@ The module is configured via mode_* commands. This defines which of the first N
 By using mode_pwm4 for example, pins 5 and 6 can be used by the camera trigger driver or by a PWM rangefinder
 driver.
 
+### Implementation
 By default the module runs on the work queue, to reduce RAM usage. It can also be run in its own thread,
 specified via start flag -t, to reduce latency.
 When running on the work queue, it schedules at a fixed frequency, and the pwm rate limits the update rate of
 the actuator_controls topics. In case of running in its own thread, the module polls on the actuator_controls topic.
 Additionally the pwm rate defines the lower-level IO timer rates.
 
+### Examples
 It is typically started with:
 $ fmu mode_pwm
 To drive all available pins.
 
-Use the 'pwm' command for further configurations (PWM rate, levels, ...).
+Capture input (rising and falling edges) and print on the console: start the fmu in one of the capture modes:
+$ fmu mode_pwm3cap1
+This will enable capturing on the 4th pin. Then do:
+$ fmu test
+
+Use the `pwm` command for further configurations (PWM rate, levels, ...), and the `mixer` command to load
+mixer files.
 )DESCR_STR");
 
 	PRINT_MODULE_USAGE_NAME("fmu", "driver");
@@ -3528,7 +3538,7 @@ Use the 'pwm' command for further configurations (PWM rate, levels, ...).
 	PRINT_MODULE_USAGE_PARAM_COMMENT("All of the mode_* commands will start the fmu if not running already");
 
 	PRINT_MODULE_USAGE_COMMAND("mode_gpio");
-	PRINT_MODULE_USAGE_COMMAND("mode_rcin");
+	PRINT_MODULE_USAGE_COMMAND_DESCR("mode_rcin", "Only do RC input, no PWM outputs");
 	PRINT_MODULE_USAGE_COMMAND_DESCR("mode_pwm", "Select all available pins as PWM");
 #if defined(BOARD_HAS_PWM)
 	PRINT_MODULE_USAGE_COMMAND("mode_pwm1");

src/modules/events/send_event.cpp

@@ -199,6 +199,7 @@ int SendEvent::print_usage(const char *reason)
 
 	PRINT_MODULE_DESCRIPTION(
 		R"DESCR_STR(
+### Description
 Background process running periodically on the LP work queue to perform housekeeping tasks.
 It is currently only responsible for temperature calibration.
 

src/modules/logger/logger.cpp

@@ -143,21 +143,26 @@ int Logger::print_usage(const char *reason)
 
 	PRINT_MODULE_DESCRIPTION(
 		R"DESCR_STR(
-System logger which logs a (configurable) set of uORB topics and system printf messages
+### Description
+System logger which logs a configurable set of uORB topics and system printf messages
 (warnings and errors) to ULog files. These can be used for system and flight performance evaluation,
 tuning, replay and crash analysis.
 
 It supports 2 backends:
 - Files: write ULog files to the file system (SD card)
 - MAVLink: stream ULog data via MAVLink to a client (the client must support this)
+
 Both backends can be enabled and used at the same time.
 
+### Implementation
 The implementation uses two threads:
 - The main thread, running at a fixed rate (or polling on a topic if started with -p) and checking for
-data updates
+  data updates
 - The writer thread, writing data to the file
+
 In between there is a write buffer with configurable size. It should be large to avoid dropouts.
 
+### Examples
 Typical usage to start logging immediately:
 $ logger start -e -t
 

src/modules/mavlink/mavlink_main.cpp

@@ -2703,19 +2703,23 @@ static void usage()
 
 	PRINT_MODULE_DESCRIPTION(
 		R"DESCR_STR(
+### Description
 This module implements the MAVLink protocol, which can be used on a Serial link or UDP network connection.
 It communicates with the system via uORB: some messages are directly handled in the module (eg. mission
 protocol), others are published via uORB (eg. vehicle_command).
 
 Streams are used to send periodic messages with a specific rate, such as the vehicle attitude.
 When starting the mavlink instance, a mode can be specified, which defines the set of enabled streams with their rates.
-For a running instance, streams can be configured via 'mavlink stream' command.
+For a running instance, streams can be configured via `mavlink stream` command.
 
 There can be multiple independent instances of the module, each connected to one serial device or network port.
 
-The implementation uses 2 threads, a sending and a receiving thread.
+### Implementation
+The implementation uses 2 threads, a sending and a receiving thread. The sender runs at a fixed rate and dynamically
+reduces the rates of the streams if the combined bandwidth is higher than the configured rate (`-r`) or the
+physical link becomes saturated. This can be checked with `mavlink status`, see if `rate mult` is less than 1.
 
-Example usage:
+### Examples
 Start mavlink on ttyS1 serial with baudrate 921600 and maximum sending rate of 80kB/s:
 $ mavlink start -d /dev/ttyS1 -b 921600 -m onboard -r 80000
 

src/platforms/common/module.cpp

@@ -44,7 +44,10 @@ pthread_mutex_t px4_modules_mutex = PTHREAD_MUTEX_INITIALIZER;
 
 void PRINT_MODULE_DESCRIPTION(const char *description)
 {
-	printf("%s\n", description);
+	// TODO: the output could be improved by:
+	// - mark titles in bold (lines starting with ##)
+	// - highlight commands (lines starting with $, or `cmd`)
+	printf("%s\n\n", description);
 }
 
 #endif /* __PX4_NUTTX */

src/platforms/px4_module.h

@@ -352,7 +352,9 @@ int ModuleBase<T>::_task_id = -1;
 
 __BEGIN_DECLS
 
-/* module documentation and command usage help methods */
+/* Module documentation and command usage help methods.
+ * These are extracted with the Tools/px_process_module_doc.py script and must be kept in sync
+ */
 
 #ifdef __PX4_NUTTX
 // disable module description on NuttX to reduce Flash usage.
@@ -361,10 +363,17 @@ __BEGIN_DECLS
 static inline void PRINT_MODULE_DESCRIPTION(const char *description) {}
 #else
 /**
- * Print module documentation (Will also be used for online documentation). This should include:
- * - provided functionality of the module
- * - high-level implementation overview
- * - examples how to use the CLI interface (if it's non-trivial)
+ * Print module documentation (will also be used for online documentation). It uses Markdown syntax
+ * and should include these sections:
+ * - ### Description
+ *   Provided functionality of the module and potentially the most important parameters.
+ * - ### Implementation
+ *   High-level implementation overview
+ * - ### Examples
+ *   Examples how to use the CLI interface (if it's non-trivial)
+ *
+ * In addition to the Markdown syntax, a line beginning with '$ ' can be used to mark a command:
+ * $ module start -p param
  */
 __EXPORT void PRINT_MODULE_DESCRIPTION(const char *description);
 #endif