stmhal: Add documentation in comments, and script to generate HTML.

Decided to write own script to pull documentation from comments in C code.
Style for writing auto generated documentation is: start line with ///
and then use standard markdown to write the comment.  Keywords
recognised by the scraper begin with backslash.  See code for examples.

Running: python gendoc.py modpyb.c accel.c adc.c dac.c extint.c i2c.c
led.c pin.c rng.c servo.c spi.c uart.c usrsw.c, will generate a HTML
structure in gendoc-out/.

gendoc.py is crude but functional.  Needed something quick, and this was
it.

1 files changed, 19 insertions, 0 deletions

diff --git a/stmhal/led.c b/stmhal/led.c
index 5a0dd7b9a..28c918e0e 100644
--- a/stmhal/led.c
+++ b/stmhal/led.c
@@ -12,6 +12,11 @@
 #include "pin.h"
 #include "genhdr/pins.h"
 
+/// \moduleref pyb
+/// \class LED - LED object
+///
+/// The LED object controls an individual LED (Light Emitting Diode).
+
 typedef struct _pyb_led_obj_t {
     mp_obj_base_t base;
     machine_uint_t led_id;
@@ -195,6 +200,10 @@ void led_obj_print(void (*print)(void *env, const char *fmt, ...), void *env, mp
     print(env, "<LED %lu>", self->led_id);
 }
 
+/// \classmethod \constructor(id)
+/// Create an LED object associated with the given LED:
+///
+///   - `id` is the LED number, 1-4.
 STATIC mp_obj_t led_obj_make_new(mp_obj_t type_in, uint n_args, uint n_kw, const mp_obj_t *args) {
     // check arguments
     mp_arg_check_num(n_args, n_kw, 1, 1, false);
@@ -211,24 +220,34 @@ STATIC mp_obj_t led_obj_make_new(mp_obj_t type_in, uint n_args, uint n_kw, const
     return (mp_obj_t)&pyb_led_obj[led_id];
 }
 
+/// \method on()
+/// Turn the LED on.
 mp_obj_t led_obj_on(mp_obj_t self_in) {
     pyb_led_obj_t *self = self_in;
     led_state(self->led_id, 1);
     return mp_const_none;
 }
 
+/// \method off()
+/// Turn the LED off.
 mp_obj_t led_obj_off(mp_obj_t self_in) {
     pyb_led_obj_t *self = self_in;
     led_state(self->led_id, 0);
     return mp_const_none;
 }
 
+/// \method toggle()
+/// Toggle the LED between on and off.
 mp_obj_t led_obj_toggle(mp_obj_t self_in) {
     pyb_led_obj_t *self = self_in;
     led_toggle(self->led_id);
     return mp_const_none;
 }
 
+/// \method intensity([value])
+/// Get or set the LED intensity.  Intensity ranges between 0 (off) and 255 (full on).
+/// If no argument is given, return the LED intensity.
+/// If an argument is given, set the LED intensity and return `None`.
 mp_obj_t led_obj_intensity(uint n_args, const mp_obj_t *args) {
     pyb_led_obj_t *self = args[0];
     if (n_args == 1) {