How to understand cargo doc errors?

help
1

Hi,

cargo test --doc throws the following error at line 70, 74 for the comments section below:

---- uart.rs - uart::UartConfigs::rxctrl (line 70) stdout ----
**error****: expected one of `,`, `...`, `..=`, `..`, `]`, or `|`, found `:`**
**-->** uart.rs:74:6

Comments on struct

  1. /** => Line 69

  2. The RW rxctrl register controls the operation of the receive channel.

  3. ```

  4. ------------------------------------------------------

  5. | RESERVED | WATERMARK | RESERVED | ENABLE|

  6. ------------------------------------------------------

  7. | [31:19]  | [18:16]   |  [15:1]  |   0   |

  8. ------------------------------------------------------

  9. ```

  10. The `rxen` bit controls wether Rx channel is active. 

  11. When cleared, the state of `rxd` pin is ignored and 

  12. no characters will be enqueued into the Rx FIFO. 

  13. The watermark field specifies the threshold at which 

  14. the Rx FIFO watermark interrupt triggers. 

  15. The `rxctrl` register is reset to 0. 

  16. Characters are enqueued when a zero (low) start bit 

  17. is seen. 

  18. */ Line 89

Can someone point me whats wrong with this way of commenting & why cargo doc complains? My problem is that I could n't understand what might be a documentation error. Until now to me, documentation is just what ever I write in my format. It seems rust has some set rules, so would be great if you can provide/point me to those set rules.

I just started going through https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html

2

Mark the code block as text (so that cargo test --doc doesn't try to run it as Rust code).

-```
+```text
 ------------------------------------------------------
 | RESERVED | WATERMARK | RESERVED | ENABLE|
 [...]
 ```
2 Likes