How to understand cargo doc errors?

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

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

This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.