Multi-line doc comments overriding raw `about` attributes

[fitzgen]

Summary

The section for help/about text in the crate-level docs say

Raw methods have priority over doc comments!

but that behavior is not exhibited when the doc comment has multiple lines.

Test Case

.tar.gz bundle with full source, Cargo.toml, and Cargo.lock

use structopt::StructOpt;

/// Doc comment.
///
/// Multi-line.
#[derive(StructOpt)]
#[structopt(about = "Raw method.")]
pub struct Options {}

fn main() {
    Options::from_args();
}

Steps to Reproduce

Untar the test case, cd into it, and run

$ cargo run -- --help

Expected Results

The about text should be

Raw method.

Actual Results

The about text reads

Doc comment.

Multi-line.

Misc.

If the doc comment is trimmed to a single line, e.g. just /// Doc comment., then the raw about method takes priority again.

Tested with structopt version 0.3.25.

[epage]

I suspect this is the same thing we are seeing with clap_derive: https://github.com/clap-rs/clap/issues/2983

[epage]

Looked a little closer. This is similar to https://github.com/clap-rs/clap/issues/2983 in that you are overriding about but not overriding long_about while your doc comment is setting both. You'll see this dual nature by passing -h instead of --help.

The way to resolve this is to also set long_about.