tox icon indicating copy to clipboard operation
tox copied to clipboard

Doc comments are interpreted as markdown code blocks.

Open bddap opened this issue 6 years ago • 1 comments

Cargo doc currently emits tons of warnings when run on this codebase.

cargo clean --doc && cargo doc
...
warning: could not parse code block as Rust code
   --> src/toxencryptsave/mod.rs:189:5
    |
189 | /     Decrypts provided `data` with `self` `PassKey`.
190 | |
191 | |     Decrypted data is smaller by [`EXTRA_LENGTH`](./constant.EXTRA_LENGTH.html)
192 | |     than encrypted data.
...   |
212 | |     assert_eq!(passkey.decrypt(&[]), Err(DecryptionError::Null));
213 | |     ```
    | |_______^
    |
    = note: error from rustc: unknown start of token: `

A bit of background. Markdown supports two modes for code blocks. The more common mode uses tick marks like so:

```
// code block..
```

but there is another mode that uses indentation:

    // code block..

The issue likely has to do with rustdoc not stripping whitespace from multiline doc comments in its unindent-comments pass.

bddap avatar Apr 29 '19 20:04 bddap

I have development profficiency and I’m a naitive english speaker so I can proofread documentation if requested.

Yes, this would be very helpful.

kpp avatar Apr 29 '19 20:04 kpp