Argh fails to remove newlines from within /** */ style doc block comments on struct fields.
- Dominant language
- Rust
- Stars
- 2k
- Forks
- 102
- PR merge metrics
- No merged PRs in 30d
Description
Hello,
I was working on a crate and found inconsistent newlines when argh prints help for a binary when using different forms of doc comments.
When fields within a `FromArgs` struct are documented using `///` style doc comments, and consecutive lines also begin with `///` every newline and break in the doc comment is ignored when the `--help` string is printed. If instead the fields are documented using `/** */` style doc block comments, newlines within that block are preserved into the output of `--help`.
I have provided some sample code which manages to reproduce it (at least on my end) and should provide help with triaging this.
| OS | Cargo Version | Rustup default |
|------------|---------------------------------------------|------------------------------------------|
| Windows 10 | cargo 1.43.0-nightly (bda50510d 2020-03-02) | nightly-x86_64-pc-windows-msvc (default) |
# Example Code
```rust
#[derive(Debug, argh::FromArgs)]
/// Demonstrating the disparity between /** */ doc comments
/// and /// doc comments
struct FailToDocument {
#[argh(switch)]
/// this doc comment will print itself correctly
/// when wrapped using multiple newlines + ///
/// at the begining
working_example: bool,
#[argh(switch)]
/** this doc comment will fail to print itself correctly
when wrapped using multiple newlines + /** */ at the
begining */
failing_example: bool,
}
fn main() {
dbg!(argh::from_env::());
}
```
| Shell | Fish Shell on Windows Subsystem for Linux |
|-------|-------------------------------------------|
```
/mnt/z/dev/stf-rs$ cargo.exe run -- --help
Finished dev [unoptimized + debuginfo] target(s) in 0.02s
Running `target\debug\stf.exe --help`
Usage: target\debug\stf.exe [--working-example] [--failing-example]
Demonstrating the disparity between /** */ doc comments and /// doc comments
Options:
--working-example this doc comment will print itself correctly when wrapped
using multiple newlines + /// at the begining
--failing-example this doc comment will fail to print itself correctly
when
wrapped using multiple newlines + /** */ at the
begining
--help display usage information
```
| Shell | Powershell |
| ----- | ---------- |
```
PS Z:\dev\stf-rs> cargo run -- --help
Finished dev [unoptimized + debuginfo] target(s) in 0.02s
Running `target\debug\stf.exe --help`
Usage: target\debug\stf.exe [--working-example] [--failing-example]
Demonstrating the disparity between /** */ doc comments and /// doc comments
Options:
--working-example this doc comment will print itself correctly when wrapped
using multiple newlines + /// at the begining
--failing-example this doc comment will fail to print itself correctly
when
wrapped using multiple newlines + /** */ at the
begining
--help display usage information
```
Contributor guide
Assessment
This issue has not been assessed yet.