cargo-readme
cargo-readme copied to clipboard
Leading sharp in generated readme's example code
In the example code here there is a leading sharp in the first line that shouldn't be there. In the generated rustdoc it's not present.
Wrong Behaviour
The sharp followed by an empty line is included. Screenshot from the generated README:
Expected Behaviour
The sharp, along with the rest of the line, should not be included. Screenshot from the rustdoc:
Setup
Issue happens on both ArchLinux and AlpineLinux, Rust/Cargo 1.38.0, Cargo-Readme 3.1.2
You might want to use a custom template with only
{{readme}}
as the content to prevent any default Templates from writing the #
.
Well, the sharp is comming from {{readme}}
section of my template. It's probably because lines starting with a sharp and followed by a whitespace are supposed to be ignored in the code examples in rustdoc, but is falsely not excluded in this case in cargo readme. So unfortunately, @Empty2k12's comment is not helpful in my case.
https://gitlab.com/msrd0/gotham-restful/blob/92410ddd5b241c5eed0bfbb91c10bd7bb7c2c865/gotham_restful/src/lib.rs#L25
This line is your culprit.
@Empty2k12 this line is not included in the rustdoc so I'm assuming it also shouldn't be in cargo readme
@msrd0 I'm not sure if this library is using rustdoc internally, so you could fix the problem yourself be removing that line. I don't understand why it's there anyways.
Well, it's there because you'd usually write an empty line between your imports and the actual code. And this library claims to read docstrings, so I believe this is an issue. Removing that line is obviously a workaround.
This library is reading docstrings, but I cannot find any instance where it claims it's doing the same as cargodoc. I would even go as far as saying that a line consisting only of #
without a space or text does not qualify as a comment. Therefore you might want to think about filing this as a bug in cargodoc. What's preventing you from having the line be black instead of a blank comment?
cargo-reame does not use cargodoc, it uses its own parser.
I will take a look at it, as soon as I can