google / google/argh

Argh fails to remove newlines from within /** */ style doc block comments on struct fields.

Open
#22 1 comment 0 reactions 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.