Standardise start/end comment tags (to our internal format) (#20)

divider/hello_divider.c

@@ -8,7 +8,7 @@
 #include "pico/stdlib.h"
 #include "hardware/divider.h"
 
-// tag::hello_divider[]
+/// \tag::hello_divider[]
 int main() {
     stdio_init_all();
     printf("Hello, divider!\n");
@@ -72,4 +72,4 @@ int main() {
     printf("outer divide %d / %d = %d\n", dividend, divisor, tmp);
     return 0;
 }
-// end::hello_divider[]
+/// \end::hello_divider[]

flash/cache_perfctr/flash_cache_perfctr.c

@@ -26,7 +26,7 @@ void __no_inline_not_in_flash_func(check)(bool cond, const char *msg) {
 void __no_inline_not_in_flash_func(check_hit_miss_invalidate)() {
     io_rw_32 *test_data_ptr = (io_rw_32 *) test_data;
 
-    //tag::check_hit_miss_invalidate[]
+    /// \tag::check_hit_miss_invalidate[]
     // Flush cache to make sure we miss the first time we access test_data
     xip_ctrl_hw->flush = 1;
     while (!(xip_ctrl_hw->stat & XIP_STAT_FLUSH_READY_BITS))
@@ -53,7 +53,7 @@ void __no_inline_not_in_flash_func(check_hit_miss_invalidate)() {
     (void) *test_data_ptr;
     check(xip_ctrl_hw->ctr_hit == 2 && xip_ctrl_hw->ctr_acc == 4,
           "Second access after invalidation should hit again");
-    //end::check_hit_miss_invalidate[]
+    /// \end::check_hit_miss_invalidate[]
 }
 
 // Some code which achieves a very high cache hit rate:

flash/xip_stream/flash_xip_stream.c

@@ -41,12 +41,12 @@ int main() {
     // writing 0 to stream_ctr.
     // It's a good idea to drain the FIFO first!
     printf("Starting stream from %p\n", random_test_data);
-    //tag::start_stream[]
+    /// \tag::start_stream[]
     while (!(xip_ctrl_hw->stat & XIP_STAT_FIFO_EMPTY))
         (void) xip_ctrl_hw->stream_fifo;
     xip_ctrl_hw->stream_addr = (uint32_t) &random_test_data[0];
     xip_ctrl_hw->stream_ctr = count_of(random_test_data);
-    //end::start_stream[]
+    /// \end::start_stream[]
 
     // Start DMA transfer from XIP stream FIFO to our buffer in memory. Use
     // the auxiliary bus slave for the DMA<-FIFO accesses, to avoid stalling
@@ -54,7 +54,7 @@ int main() {
     // example, but it can have a huge effect on DMA throughput.
 
     printf("Starting DMA\n");
-    //tag::start_dma[]
+    /// \tag::start_dma[]
     const uint dma_chan = 0;
     dma_channel_config cfg = dma_channel_get_default_config(dma_chan);
     channel_config_set_read_increment(&cfg, false);
@@ -68,7 +68,7 @@ int main() {
             count_of(random_test_data), // Transfer count
             true                        // Start immediately!
     );
-    //end::start_dma[]
+    /// \end::start_dma[]
 
     dma_channel_wait_for_finish_blocking(dma_chan);
 
@@ -85,4 +85,4 @@ int main() {
     }
     if (!mismatch)
         printf("Data check OK\n");
-}
+}

gpio/hello_7segment/hello_7segment.c

@@ -42,7 +42,7 @@ int bits[10] = {
         0x67   // 9
 };
 
-// tag::hello_gpio[]
+/// \tag::hello_gpio[]
 int main() {
     stdio_init_all();
     printf("Hello, 7segment - press button to count down!\n");
@@ -92,4 +92,4 @@ int main() {
 
     return 0;
 }
-// end::hello_gpio[]
+/// \end::hello_gpio[]

multicore/hello_multicore/multicore.c

@@ -29,7 +29,7 @@ int main() {
     stdio_init_all();
     printf("Hello, multicore!\n");
 
-    ///tag::setup_multicore[]
+    /// \tag::setup_multicore[]
 
     multicore_launch_core1(core1_entry);
 
@@ -44,5 +44,5 @@ int main() {
         printf("It's all gone well on core 0!");
     }
 
-    ///end::setup_multicore[]
-}
+    /// \end::setup_multicore[]
+}

multicore/multicore_fifo_irqs/multicore_fifo_irqs.c

@@ -9,7 +9,7 @@
 #include "pico/multicore.h"
 #include "hardware/irq.h"
 
-///tag::multicore_fifo_irqs[]
+/// \tag::multicore_fifo_irqs[]
 
 #define FLAG_VALUE1 123
 #define FLAG_VALUE2 321
@@ -73,4 +73,4 @@ int main() {
         tight_loop_contents();
 }
 
-///end::multicore_fifo_irqs[]
+/// \end::multicore_fifo_irqs[]

multicore/multicore_runner/multicore_runner.c

@@ -8,7 +8,7 @@
 #include "pico/stdlib.h"
 #include "pico/multicore.h"
 
-///tag::multicore_dispatch[]
+/// \tag::multicore_dispatch[]
 
 #define FLAG_VALUE 123
 
@@ -80,4 +80,4 @@ int main() {
 
 }
 
-///end::multicore_dispatch[]
+/// \end::multicore_dispatch[]

pwm/hello_pwm/hello_pwm.c

@@ -10,7 +10,7 @@
 #include "hardware/pwm.h"
 
 int main() {
-    ///tag::setup_pwm[]
+    /// \tag::setup_pwm[]
 
     // Tell GPIO 0 and 1 they are allocated to the PWM
     gpio_set_function(0, GPIO_FUNC_PWM);
@@ -27,7 +27,7 @@ int main() {
     pwm_set_chan_level(slice_num, PWM_CHAN_B, 3);
     // Set the PWM running
     pwm_set_enabled(slice_num, true);
-    ///end::setup_pwm[]
+    /// \end::setup_pwm[]
 
     // Note we could also use pwm_set_gpio_level(gpio, x) which looks up the
     // correct slice and channel for a given GPIO.

usb/device/dev_lowlevel/dev_lowlevel.c

@@ -480,7 +480,7 @@ static void usb_handle_buff_status() {
  * @brief USB interrupt handler
  *
  */
-// tag::isr_setup_packet[]
+/// \tag::isr_setup_packet[]
 void isr_usbctrl(void) {
     // USB interrupt handler
     uint32_t status = usb_hw->ints;
@@ -492,7 +492,7 @@ void isr_usbctrl(void) {
         usb_hw_clear->sie_status = USB_SIE_STATUS_SETUP_REC_BITS;
         usb_handle_setup_packet();
     }
-// end::isr_setup_packet[]
+/// \end::isr_setup_packet[]
 
     // Buffer status, one or more buffers have completed
     if (status & USB_INTS_BUFF_STATUS_BITS) {
@@ -569,4 +569,4 @@ int main(void) {
     }
 
     return 0;
-}
+}