minor: Fix various decoder doc comments

src/devices/ambient_weather.c

@@ -10,8 +10,8 @@
     (at your option) any later version.
 */
 
-/*
-Decode Ambient Weather F007TH, F012TH, TF 30.3208.02, SwitchDoc F016TH
+/**
+Decode Ambient Weather F007TH, F012TH, TF 30.3208.02, SwitchDoc F016TH.
 
 Devices supported:
 

src/devices/brennenstuhl_rcs_2044.c

@@ -9,7 +9,7 @@
     (at your option) any later version.
 */
 
-/*
+/**
 Brennenstuhl RCS 2044 remote control on 433.92MHz likely x1527.
 
 Receiver for the "RCS 2044 N Comfort Wireless Controller Set" sold under

src/devices/current_cost.c

@@ -12,6 +12,11 @@
 
 #include "decoder.h"
 
+/**
+CurrentCost TX, CurrentCost EnviR current sensors.
+
+@todo Documentation needed.
+*/
 static int current_cost_decode(r_device *decoder, bitbuffer_t *bitbuffer)
 {
     data_t *data;

src/devices/digitech_xc0324.c

@@ -8,7 +8,7 @@
     the Free Software Foundation; either version 2 of the License, or
     (at your option) any later version.
 */
-/** @fn static int xc0324_callback(r_device *decoder, bitbuffer_t *bitbuffer)
+/**
 Digitech XC-0324 device.
 
 The encoding is pulse position modulation

src/devices/elv.c

@@ -23,7 +23,11 @@ static uint16_t AD_POP(uint8_t *bb, uint8_t bits, uint8_t bit)
     return val;
 }
 
-// based on fs20.c
+/**
+ELV EM 1000 decoder.
+
+based on fs20.c
+*/
 static int em1000_callback(r_device *decoder, bitbuffer_t *bitbuffer)
 {
     data_t *data;

src/devices/emontx.c

@@ -24,16 +24,20 @@ struct emontx {
 };
 #pragma pack(pop)
 
-// This is the JeeLibs RF12 packet format as described at
-// http://jeelabs.org/2011/06/09/rf12-packet-format-and-design/
-//
-// The RFM69 chip misses out the zero bit at the end of the
-// 0xAA 0xAA 0xAA preamble; the receivers only use it to set
-// up the bit timing, and they look for the 0x2D at the start
-// of the packet. So we'll do the same — except since we're
-// specifically looking for emonTx packets, we can require a
-// little bit more. We look for a group of 0xD2, and we
-// expect the CDA bits in the header to all be zero:
+/** @fn int emontx_callback(r_device *decoder, bitbuffer_t *bitbuffer)
+OpenEnergyMonitor.org emonTx sensor protocol.
+
+This is the JeeLibs RF12 packet format as described at
+http://jeelabs.org/2011/06/09/rf12-packet-format-and-design/
+
+The RFM69 chip misses out the zero bit at the end of the
+0xAA 0xAA 0xAA preamble; the receivers only use it to set
+up the bit timing, and they look for the 0x2D at the start
+of the packet. So we'll do the same — except since we're
+specifically looking for emonTx packets, we can require a
+little bit more. We look for a group of 0xD2, and we
+expect the CDA bits in the header to all be zero:
+*/
 static unsigned char preamble[3] = { 0xaa, 0xaa, 0xaa };
 static unsigned char pkt_hdr_inverted[3] = { 0xd2, 0x2d, 0xc0 };
 static unsigned char pkt_hdr[3] = { 0x2d, 0xd2, 0x00 };

src/devices/esa.c

@@ -35,6 +35,11 @@ static uint8_t decrypt_esa(uint8_t *b)
     return crc;
 }
 
+/**
+ELV Energy Counter ESA 1000/2000.
+
+@todo Documentation needed.
+*/
 static int esa_cost_callback(r_device *decoder, bitbuffer_t *bitbuffer)
 {
     data_t *data;

src/devices/fineoffset.c

@@ -548,44 +548,43 @@ static int fineoffset_WH25_callback(r_device *decoder, bitbuffer_t *bitbuffer)
     return 1;
 }
 
-/*
-Fine Offset WH51, ECOWITT WH51, MISOL/1 Soil Moisture Sensor
+/**
+Fine Offset WH51, ECOWITT WH51, MISOL/1 Soil Moisture Sensor.
 
 Also: SwitchDoc Labs SM23 Soil Moisture Sensor.
 
 Test decoding with: rtl_433 -f 433920000  -X "n=soil_sensor,m=FSK_PCM,s=58,l=58,t=5,r=5000,g=4000,preamble=aa2dd4"
 
 Data format:
 
-               00 01 02 03 04 05 06 07 08 09 10 11 12 13
-aa aa aa 2d d4 51 00 6b 58 6e 7f 24 f8 d2 ff ff ff 3c 28 8
-               FF II II II TB YY MM ZA AA XX XX XX CC SS
-
-Sync:     aa aa aa ...
-Preamble: 2d d4
-FF:       Family code 0x51 (ECOWITT/FineOffset WH51)
-IIIIII:   ID (3 bytes)
-T:        Transmission period boost: highest 3 bits set to 111 on moisture change and decremented each transmission;
-          if T = 0 period is 70 sec, if T > 0 period is 10 sec
-B:        Battery voltage: lowest 5 bits are battery voltage * 10 (e.g. 0x0c = 12 = 1.2V). Transmitter works down to 0.7V (0x07)
-YY:       ? Fixed: 0x7f
-MM:       Moisture percentage 0%-100% (0x00-0x64) MM = (AD - 70) / (450 - 70)
-Z:        ? Fixed: leftmost 7 bit 1111 100
-AAA:      9 bit AD value MSB byte[07] & 0x01, LSB byte[08]
-XXXXXX:   ? Fixed: 0xff 0xff 0xff
-CC:       CRC of the preceding 12 bytes (Polynomial 0x31, Initial value 0x00, Input not reflected, Result not reflected)
-SS:       Sum of the preceding 13 bytes % 256
+                   00 01 02 03 04 05 06 07 08 09 10 11 12 13
+    aa aa aa 2d d4 51 00 6b 58 6e 7f 24 f8 d2 ff ff ff 3c 28 8
+                   FF II II II TB YY MM ZA AA XX XX XX CC SS
+
+- Sync:     aa aa aa ...
+- Preamble: 2d d4
+- FF:       Family code 0x51 (ECOWITT/FineOffset WH51)
+- IIIIII:   ID (3 bytes)
+- T:        Transmission period boost: highest 3 bits set to 111 on moisture change and decremented each transmission;
+-           if T = 0 period is 70 sec, if T > 0 period is 10 sec
+- B:        Battery voltage: lowest 5 bits are battery voltage * 10 (e.g. 0x0c = 12 = 1.2V). Transmitter works down to 0.7V (0x07)
+- YY:       ? Fixed: 0x7f
+- MM:       Moisture percentage 0%-100% (0x00-0x64) MM = (AD - 70) / (450 - 70)
+- Z:        ? Fixed: leftmost 7 bit 1111 100
+- AAA:      9 bit AD value MSB byte[07] & 0x01, LSB byte[08]
+- XXXXXX:   ? Fixed: 0xff 0xff 0xff
+- CC:       CRC of the preceding 12 bytes (Polynomial 0x31, Initial value 0x00, Input not reflected, Result not reflected)
+- SS:       Sum of the preceding 13 bytes % 256
 
 See http://www.ecowitt.com/upfile/201904/WH51%20Manual.pdf for relationship between AD and moisture %
 
 Short explanation:
-Soil Moisture Percentage = (Moisture AD – 0%AD) / (100%AD – 0%AD) * 100
-0%AD = 70
-100%AD = 450 (manual states 500, but sensor internal computation are closer to 450)
-If sensor-calculated moisture percentage are inaccurate at low/high values, use the AD value and the above formaula
-changing 0%AD and 100%AD to cover the full scale from dry to damp
+- Soil Moisture Percentage = (Moisture AD – 0%AD) / (100%AD – 0%AD) * 100
+- 0%AD = 70
+- 100%AD = 450 (manual states 500, but sensor internal computation are closer to 450)
+- If sensor-calculated moisture percentage are inaccurate at low/high values, use the AD value and the above formaula
+  changing 0%AD and 100%AD to cover the full scale from dry to damp
 */
-
 static int fineoffset_WH51_callback(r_device *decoder, bitbuffer_t *bitbuffer)
 {
     data_t *data;

src/devices/flex.c

@@ -144,6 +144,9 @@ static void render_getters(data_t *data, uint8_t *bits, struct flex_params *para
     }
 }
 
+/**
+Generic flex decoder.
+*/
 static int flex_callback(r_device *decoder, bitbuffer_t *bitbuffer)
 {
     int i;

src/devices/fs20.c

@@ -8,7 +8,7 @@
     published by the Free Software Foundation.
 */
 
-/*
+/**
 Simple FS20 remote decoder.
 
 Frequency: use rtl_433 -f 868.35M

src/devices/insteon.c

@@ -9,7 +9,7 @@
     (at your option) any later version.
 */
 
-/** @fn int insteon_callback(r_device *decoder, bitbuffer_t *bitbuffer)
+/** @fn int parse_insteon_pkt(r_device *decoder, bitbuffer_t *bits, unsigned int row, unsigned int start_pos)
 Insteon RF decoder.
 
     "Insteon is a home automation (domotics) technology that enables

src/devices/mebus.c

@@ -9,7 +9,12 @@
 
 #include "decoder.h"
 
-static int mebus433_callback(r_device *decoder, bitbuffer_t *bitbuffer)
+/**
+Mebus 433.
+
+@todo Documentation needed.
+*/
+static int mebus433_decode(r_device *decoder, bitbuffer_t *bitbuffer)
 {
     bitrow_t *bb = bitbuffer->bb;
     int16_t temp;
@@ -81,7 +86,7 @@ r_device mebus433 = {
         .long_width  = 1600, // guessed, no samples available
         .gap_limit   = 2400,
         .reset_limit = 6000,
-        .decode_fn   = &mebus433_callback,
+        .decode_fn   = &mebus433_decode,
         .disabled    = 1, // add docs, tests, false positive checks and then re-enable
         .fields      = output_fields,
 };

src/devices/oregon_scientific.c

@@ -205,6 +205,11 @@ static int validate_os_v2_message(r_device *decoder, unsigned char *msg, int bit
     return 1;
 }
 
+/**
+Various Oregon Scientific protocols.
+
+@todo Documentation needed.
+*/
 static int oregon_scientific_v2_1_decode(r_device *decoder, bitbuffer_t *bitbuffer)
 {
     uint8_t *b = bitbuffer->bb[0];
@@ -556,6 +561,11 @@ static int oregon_scientific_v2_1_decode(r_device *decoder, bitbuffer_t *bitbuff
 // ceil( (335 + 11) / 8 )
 #define EXPECTED_NUM_BYTES 44
 
+/**
+Various Oregon Scientific protocols.
+
+@todo Documentation needed.
+*/
 static int oregon_scientific_v3_decode(r_device *decoder, bitbuffer_t *bitbuffer)
 {
     uint8_t *b = bitbuffer->bb[0];

src/devices/radiohead_ask.c

@@ -6,7 +6,7 @@
     the Free Software Foundation; either version 2 of the License, or
     (at your option) any later version.
 */
-/**
+/** @fn int radiohead_ask_callback(r_device *decoder, bitbuffer_t *bitbuffer)
 RadioHead ASK (generic) protocol.
 
 Default transmitter speed is 2000 bits per second, i.e. 500 us per bit.
@@ -51,6 +51,9 @@ static uint8_t symbol_6to4(uint8_t symbol)
     return 0xFF; // Not found
 }
 
+/**
+Radiohead ASK parser.
+*/
 static int radiohead_ask_extract(r_device *decoder, bitbuffer_t *bitbuffer, uint8_t row, /*OUT*/ uint8_t *payload)
 {
     int len = bitbuffer->bits_per_row[row];
@@ -175,6 +178,11 @@ static int radiohead_ask_callback(r_device *decoder, bitbuffer_t *bitbuffer)
     return 1;
 }
 
+/**
+Sensible Living Mini-Plant Moisture Sensor.
+
+@todo Documentation needed.
+*/
 static int sensible_living_callback(r_device *decoder, bitbuffer_t *bitbuffer)
 {
     data_t *data;

src/devices/secplus_v2.c

@@ -237,6 +237,10 @@ static int secplus_v2_decode_v2_half(r_device *decoder, bitbuffer_t *bits, uint8
 static const uint8_t _preamble[] = {0xaa, 0xaa, 0x95, 0x60};
 unsigned _preamble_len           = 28;
 
+/**
+Security+ 2.0 rolling code.
+@sa secplus_v2_decode_v2_half()
+*/
 static int secplus_v2_callback(r_device *decoder, bitbuffer_t *bitbuffer)
 {
     unsigned search_index = 0;

src/devices/silvercrest.c

@@ -11,6 +11,11 @@
 
 #include "decoder.h"
 
+/**
+Silvercrest remote decoder.
+
+@todo Documentation needed.
+*/
 static int silvercrest_callback(r_device *decoder, bitbuffer_t *bitbuffer)
 {
     uint8_t const cmd_lu_tab[16] = {2, 3, 0, 1, 4, 5, 7, 6, 0xC, 0xD, 0xF, 0xE, 8, 9, 0xB, 0xA};

src/devices/simplisafe.c

@@ -10,9 +10,13 @@
 
     License: GPL v2+ (or at your choice, any other OSI-approved Open Source license)
 */
-/**
+/** @fn int ss_sensor_callback(r_device *decoder, bitbuffer_t *bitbuffer)
 Protocol of the SimpliSafe Sensors.
 
+@sa ss_sensor_parser()
+@sa ss_pinentry_parser()
+@sa ss_keypad_commands()
+
 The data is sent leveraging a PiWM Encoding where a long is 1, and a short is 0
 
 All bytes are sent with least significant bit FIRST (1000 0111 = 0xE1)
@@ -44,6 +48,9 @@ static void ss_get_id(char *id, uint8_t *b)
     *p = '\0';
 }
 
+/**
+SimpliSafe protocol for sensors.
+*/
 static int ss_sensor_parser(r_device *decoder, bitbuffer_t *bitbuffer, int row)
 {
     data_t *data;
@@ -85,6 +92,9 @@ static int ss_sensor_parser(r_device *decoder, bitbuffer_t *bitbuffer, int row)
     return 1;
 }
 
+/**
+SimpliSafe protocol for pinentry.
+*/
 static int ss_pinentry_parser(r_device *decoder, bitbuffer_t *bitbuffer, int row)
 {
     data_t *data;
@@ -119,6 +129,9 @@ static int ss_pinentry_parser(r_device *decoder, bitbuffer_t *bitbuffer, int row
     return 1;
 }
 
+/**
+SimpliSafe protocol for keypad commands.
+*/
 static int ss_keypad_commands(r_device *decoder, bitbuffer_t *bitbuffer, int row)
 {
     data_t *data;
@@ -155,10 +168,6 @@ static int ss_keypad_commands(r_device *decoder, bitbuffer_t *bitbuffer, int row
     return 1;
 }
 
-/**
-Protocol of the SimpliSafe Sensors.
-@sa ss_sensor_parser() ss_pinentry_parser() ss_keypad_commands()
-*/
 static int ss_sensor_callback(r_device *decoder, bitbuffer_t *bitbuffer)
 {
     // Require two identical rows.

src/devices/ts_ft002.c

@@ -8,8 +8,8 @@
     the Free Software Foundation; either version 2 of the License, or
     (at your option) any later version.
 */
-/*
-TS-FT002 Wireless Ultrasonic Tank Liquid Level Meter With Temperature Sensor
+/**
+TS-FT002 Wireless Ultrasonic Tank Liquid Level Meter With Temperature Sensor.
 
 PPM with 500 us pulse, 464 us short gap (0), 948 us long gap (1), 1876 us packet gap, two packets per transmission.
 

tests/symbolizer.py

@@ -100,6 +100,9 @@ def process_source(path, name):
                 if fName:
                     if fName not in links:
                         links[fName] = {"src": name, "type": "func"}
+                    if dSee:
+                        links[fName].update({"doc_line": dLine, "doc_see": dSee})
+                        dSee = None
                     links[fName].update({"doc_line": dLine, "doc": doc})
                     doc = None
                     fName = None
@@ -141,6 +144,7 @@ def process_source(path, name):
                 continue
             m = re.match(r'\s*/\*\*', line)
             if m:
+                fName = None
                 captureDoc = True
                 dLine = i + 1
                 doc = ''
@@ -279,7 +283,8 @@ def check_symbols(symbols):
             if "line" not in d:
                 err(f"::error file={d['src']}::func missing ({f})")
             if "doc" not in d or not d["doc"]:
-                #err(f"::warning file={d['src']},line={d['line']}::doc missing for {f}")
+                if "doc_see" not in d or not d["doc_see"]:
+                    err(f"::warning file={d['src']},line={d['line']}::doc missing for {f}")
                 pass
 
         if d["type"] == "model":