Markdown codeblock changes

Signed-off-by: Sara Damiano <sdamiano@stroudcenter.org>
EnviroDIY · Aug 13, 2024 · b59e48a · b59e48a
1 parent 683f2ee
commit b59e48a
Show file tree

Hide file tree

Showing 5 changed files with 58 additions and 54 deletions.
diff --git a/ChangeLog.md b/ChangeLog.md
@@ -38,7 +38,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Offloaded some internal header file documentation to markdown files
 - Consolidated redundant `READTIME` and `TCNTX` macros, removing `TCNTX`
-- Removed documation @m_span commands
+- Removed documation m_span commands
 
 ### Fixed
 

diff --git a/README.md b/README.md
@@ -21,7 +21,8 @@ Extensive documentation on the SDI-12 functions and classes is available here:
 
 ### Renaming Notice<!-- {#mainpage_rename} -->
 
-**As of version 2.0.0 this library was renamed from "Arduino-SDI-12" to simply "SDI-12" to comply with requirements for inclusion in the Arduino.cc's IDE and Library Manager.**
+> [!IMPORTANT]
+> **As of version 2.0.0 this library was renamed from "Arduino-SDI-12" to simply "SDI-12" to comply with requirements for inclusion in the Arduino.cc's IDE and Library Manager.**
 
 [//]: # ( @tableofcontents )
 

diff --git a/docs/CreatingACharacter.md b/docs/CreatingACharacter.md
@@ -59,22 +59,22 @@ And lets remind ourselves of the static variables we're using to store states:
 The `rxState`, `rxMask`, and `rxValue` all work together to form a character.
 When we're waiting for a start bit `rxValue` is empty, `rxMask` has only the bottom bit set, and `rxState` is set to WAITING-FOR-START-BIT:
 
-```
-    rxValue: |     0   0   0   0   0   0   0   0
--------------|-----------------------------------
-     rxMask: |     0   0   0   0   0   0   0   1
-    rxState: |     1   1   1   1   1   1   1   1
+```unparsed
+| rxValue: | 0   0   0   0   0   0   0   0 |
+| -------- | ----------------------------- |
+| rxMask:  | 0   0   0   0   0   0   0   1 |
+| rxState: | 1   1   1   1   1   1   1   1 |
 ```
 
 ### The Start of a Character<!-- {#rx_mask_start} -->
 
 After we get a start bit, the `startChar()` function creates a blank slate for the new character, so our values are:
 
-```
-    rxValue: |     0   0   0   0   0   0   0   0
--------------|-----------------------------------
-     rxMask: |     0   0   0   0   0   0   0   1
-    rxState: |     0   0   0   0   0   0   0   0
+```unparsed
+| rxValue: | 0   0   0   0   0   0   0   0 |
+| -------- | ----------------------------- |
+| rxMask:  | 0   0   0   0   0   0   0   1 |
+| rxState: | 0   0   0   0   0   0   0   0 |
 ```
 
 ### The Interrupt Fires<!-- {#rx_mask_fire} -->
@@ -94,22 +94,22 @@ For **each bit time that passed**, we apply the `rxMask` to the `rxValue`.
 
 - if the data bit received is LOW (1) we do an `|=` (bitwise OR) between the `rxMask` and the `rxValue`
 
-```
-    rxValue: |     0   0   0   0   0   0   0   1
--------------|---------------------------------^- bit-wise or puts the one
-     rxMask: |     0   0   0   0   0   0   0   1      from the rxMask into
-    rxState: |     0   0   0   0   0   0   0   0      the rxValue
+```unparsed
+| rxValue: | 0   0   0   0   0   0   0   1 |
+| -------- | ----------------------------- |^- bit-wise or puts the one
+|  rxMask: | 0   0   0   0   0   0   0   1 |   from the rxMask into
+| rxState: | 0   0   0   0   0   0   0   0 |   the rxValue
 ```
 
 #### A HIGH/0 Bit<!-- {#rx_mask_high} -->
 
 - if the data bit received is HIGH (0) we do nothing
 
-```
-    rxValue: |     0   0   0   0   0   0   0   0
--------------|---------------------------------x- nothing happens
-     rxMask: |     0   0   0   0   0   0   0   1
-    rxState: |     0   0   0   0   0   0   0   0
+```unparsed
+| rxValue: | 0   0   0   0   0   0   0   0 |
+| -------- | ----------------------------- |x- nothing happens
+|  rxMask: | 0   0   0   0   0   0   0   1 |
+| rxState: | 0   0   0   0   0   0   0   0 |
 ```
 
 #### Shifting Up<!-- {#rx_mask_shift} -->
@@ -120,13 +120,13 @@ The top bit falls off.
   - we always add a 0 on the `rxMask` and the `rxValue`
   - the values of the second bit of the `rxValue` (?) depends on what we did in the step above
 
-```
-    rxValue: |     0        <--- | 0   0   0   0   0   0   ?   0 <--- add a zero
--------------|-------------------|---------------------------|---
-     rxMask: |     0        <--- | 0   0   0   0   0   0   1   0 <--- add a zero
-    rxState: |     0        <--- | 0   0   0   0   0   0   0   1 <--- add a one
--------------|-------------------|---------------------------|---
-             | falls off the top |                           | added to the bottom
+```unparsed
+| rxValue:          | 0        <---       | 0   0   0   0   0   0   ?   0 <--- add a zero |
+| ----------------- | ------------------- | --------------------------------------------- |
+| rxMask:           | 0        <---       | 0   0   0   0   0   0   1   0 <--- add a zero |
+| rxState:          | 0        <---       | 0   0   0   0   0   0   0   1 <--- add a one  |
+| ----------------- | ------------------- | --------------------------------------------- |
+| ----------------- | ^ falls off the top | ------- added to the bottom ^                 |
 ```
 
 ### A Finished Character<!-- {#rx_mask_fin} -->
@@ -136,11 +136,11 @@ The `rxMask`  will have the one in the top bit.
 And the rxState will be filled - which just happens to be the value of `WAITING-FOR-START-BIT` for the next character.
 
 
-```
-    rxValue: |     ?   ?   ?   ?   ?   ?   ?   ?
--------------|-----------------------------------
-     rxMask: |     1   0   0   0   0   0   0   0
-    rxState: |     1   1   1   1   1   1   1   1
+```unparsed
+| rxValue: | ?   ?   ?   ?   ?   ?   ?   ? |
+| -------- | ----------------------------- |
+| rxMask:  | 1   0   0   0   0   0   0   0 |
+| rxState: | 1   1   1   1   1   1   1   1 |
 ```
 
 ## The Full Interrupt Function<!-- {#rx_fxn} -->

diff --git a/docs/OverviewOfInterrupts.md b/docs/OverviewOfInterrupts.md
@@ -3,6 +3,7 @@
 [//]: # ( @tableofcontents )
 
 [//]: # ( @cond GitHub )
+
 - [Overview of Interrupts](#overview-of-interrupts)
   - [What is an Interrupt?](#what-is-an-interrupt)
   - [Directly Controlling Interrupts on an AVR Board](#directly-controlling-interrupts-on-an-avr-board)
@@ -13,6 +14,7 @@
 [//]: # ( @endcond )
 
 ## What is an Interrupt?<!-- {#interrupts_what} -->
+
 An interrupt is a signal that causes the microcontroller to halt execution of the program, and perform a subroutine known as an interrupt handler or Interrupt Service Routine (ISR).
 After the ISR, program execution continues where it left off.
 This allows the microcontroller to efficiently handle a time-sensitive function such as receiving a burst of data on one of its pins, by not forcing the microcontroller to wait for the data.
@@ -32,22 +34,26 @@ For AVR processors, like the Arduino Uno or the EnviroDIY Mayfly, we have to use
 **Registers**: small 1-byte (8-bit) stores of memory directly accessible by processor
 PCMSK0, PCMSK1, PCMSK2, PCMSK3
 
-**PCICRx**: a register where the three least significant bits enable or disable pin change interrupts on a range of pins
+`PCICRx`: a register where the three least significant bits enable or disable pin change interrupts on a range of pins
+
 - i.e. {0,0,0,0,0,PCIE2,PCIE1,PCIE0}, where PCIE2 maps to PCMSK2, PCIE1 maps to PCMSK1, and PCIE0 maps to PCMSK0.
 
-**PCMSKx**: a register that stores the state (enabled/disabled) of pin change interrupts on a single pin
+`PCMSKx`: a register that stores the state (enabled/disabled) of pin change interrupts on a single pin
+
 - Each bit stores a 1 (enabled) or 0 (disabled).
 
 On an Arduino Uno:
+
 - There is on PCICR register controlling three ranges of pins
 - There are three mask registers (PCMSK0, PCMSK1, and PCMSK2) controlling individual pins.
 - Looking at one mask register, PCMSK0:
-    - the 8 bits represent: PCMSK0 {PCINT7, PCINT6, PCINT5, PCINT4, PCINT3, PCINT2, PCINT1, PCINT0}
-    - these map to:         PCMSK0 {XTAL2,  XTAL1,  Pin 13, Pin 12, Pin 11, Pin 10, Pin 9,  Pin 8}
+  - the 8 bits represent: PCMSK0 {PCINT7, PCINT6, PCINT5, PCINT4, PCINT3, PCINT2, PCINT1, PCINT0}
+  - these map to:         PCMSK0 {XTAL2,  XTAL1,  Pin 13, Pin 12, Pin 11, Pin 10, Pin 9,  Pin 8}
+
+`noInterrupts()`: a function to globally disable interrupts (of all types)
 
-**noInterrupts()**: a function to globally disable interrupts (of all types)
+`interrupts()`: a function to globally enable interrupts (of all types)
 
-**interrupts()**: a function to globally enable interrupts (of all types)
 - interrupts will only occur if the requisite registers are set (e.g. PCMSK and PCICR).
 
 ### Enabling an Interrupt<!-- {#interrupts_enable} -->
@@ -87,15 +93,15 @@ Or equivalently:  `(1<<1)`, we get: `{00000010}`.
 To use the mask to set the bit of interest we use the bitwise or operator `|`.
 We will use the compact `|=` notation which does the operation and then stores the result back into the left hand side.
 
-
 So the operation:
 
 ```cpp
 *digitalPinToPCMSK(_dataPin) |= (1<<digitalPinToPCMSKbit(9));
 ```
+
 Accomplishes:
 
-```
+```unparsed
     (1<<digitalPinToPCMSKbit(9))              {00000010}
 
     PCMSK0                               |    {00000000}
@@ -105,12 +111,10 @@ Accomplishes:
                                               {00000010}
 ```
 
-
 We must also enable the global control for the interrupt. This is done in a similar fashion:
 
 `*digitalPinToPCICR(_dataPin) |= (1<<digitalPinToPCICRbit(_dataPin));`
 
-
 Now let's assume that part of your Arduino sketch outside of SDI-12 had set a pin change interrupt on pin 13.
 Pin 9 and pin 13 are on the same PCMSK in the case of the Arduino Uno.
 
@@ -120,7 +124,7 @@ This time before we set the bit for pin nine,
 
 So now:
 
-```
+```unparsed
     (1<<digitalPinToPCMSKbit(9))              {00000010}
 
     PCMSK0                               |    {00100000}
@@ -132,12 +136,11 @@ So now:
 
 By using a bitmask and bitwise operation, we have successfully enabled pin 9 without effecting the state of pin 13.
 
-
 ### Disabling an Interrupt<!-- {#interrupts_disable} -->
 
 When the we would like to put the SDI-12 object in the DISABLED state, (e.g. the destructor is called), we need to make sure the bit corresponding to the data pin is unset.
 
-Let us consider again the case of where an interrupt has been enabled on pin 13: {00100010}.
+Let us consider again the case of where an interrupt has been enabled on pin 13: `{00100010}`.
 We want to be sure not to disturb this interrupt when disabling the interrupt on pin 9.
 
 We will make use of similar macros, but this time we will use an inverted bit mask and the AND operation.
@@ -150,7 +153,7 @@ The inversion symbol `~` modifies the result to `{11111101}`
 
 So to finish our example:
 
-```
+```unparsed
     ~(1<<digitalPinToPCMSKbit(9))             {11111101}
 
     PCMSK0                               &    {00100010}
@@ -163,16 +166,16 @@ So to finish our example:
 So only the interrupt on pin 13 remains set.
 As a matter of book keeping, if we unset the last bit in the PCMSK, we ought to also unset the respective bit in the PCICR.
 
-    `!(*digitalPinToPCMSK(9)`
+`!(*digitalPinToPCMSK(9)`
 
-        will evaluate TRUE if PCMSK {00000000}
-
-        will evaluate FALSE if PCMSK != {00000000}
+- will evaluate TRUE if PCMSK == `{00000000}`
+- will evaluate FALSE if PCMSK != `{00000000}`
 
 In this case, pin 13 is set, so the expression would be FALSE.
 If we go back to the original case without pin 13, the expression after disabling pin 9 would evaluate to TRUE.
 
 Therefore if we evaluate to TRUE, we should tidy up:
+
 ```cpp
 if(!*digitalPinToPCMSK(_dataPin)){
       *digitalPinToPCICR(_dataPin) &= ~(1<<digitalPinToPCICRbit(_dataPin));

diff --git a/src/SDI12.h b/src/SDI12.h
@@ -944,8 +944,8 @@ class SDI12 : public Stream {
    * of the content of the message.
    *
    * @param respWithCRC The full SDI-12 message, including the CRC at the end.
-   * @return *true* The CRC matches and the message is valid
-   * @return *false* The CRC doesn't match; the conversation should be retried.
+   * @return True if the CRC matches and the message is valid, false if the CRC doesn't
+   * match and the message could be retried.
    */
   bool verifyCRC(String& respWithCRC);