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

[firestack]

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

#[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::<FailToDocument>());
}

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

[fadeevab]

@firestack I'm not a maintainer, just let me put in my two cents here.

Seems like argh doesn't do string processing for the doc comments at all (I mean removing spaces and new lines). What it does it is simply like this:

/// One
/// Two
" One" +
" Two"

Or

/** One
       Two */
" One
       Two"

So I believe the semantics is the same as when you're working with strings in the code. In your code if you want exact formatting you don't split a string and write like this:

let doc = "
Formatting is
      everywhere"

And if you want a long string you concatenate them:

let doc = "Formatting".to_owned() +
                 " is" +
                 " not everywhere";

If to do a string processing removing spaces, then what if you wanted to do some formatting in your doc string?

So I believe this simple approach is good enough and it should not get fixed ("this is not a bug but a feature" :))