When deriving Parser, multi-sentence doc comments have final period removed

[nyanpasu64]

Please complete the following tasks

• I have searched the discussions
• I have searched the existing issues

Rust Version

rustc 1.58.1 (db9d1b20b 2022-01-20)

Clap Version

3.0.13

Minimal reproducible code

use std::path::PathBuf;

use clap::Parser;

#[derive(Parser)]
#[clap(author, version, about, long_about = None)]
struct Cli {
    /// If omitted, installs a shortcut to itself to the "Send To" menu.
    /// If passed, installs a shortcut to the .exe to the start menu.
    exe: Option<PathBuf>,
}

fn main() {
    Cli::parse();
}

Steps to reproduce the bug with the above code

cargo run -- -h

Actual Behaviour

The doc comment consists of multiple sentences, and it's difficult to rewrite it in a single sentence without losing critical information. But the final period is removed, resulting in a jarring and ungrammatical result:

send-to-start 0.1.0

USAGE:
    send-to-start.exe [EXE]

ARGS:
    <EXE>    If omitted, installs a shortcut to itself to the "Send To" menu. If passed,
             installs a shortcut to the .exe to the start menu

OPTIONS:
    -h, --help       Print help information
    -V, --version    Print version information

In other cases, I've had to spend effort rewriting my doc comments into a single summary sentence, followed by extra paragraphs of explanation. Perhaps it's better for users, perhaps not. As an author I wish it wasn't necessary to do so to avoid structopt breaking my help output.

Also as a user I dislike how -h prints short output and --help prints multi-paragraph output, even though the help output (-h, --help) implies that these 2 commands are interchangeable. As a result, I often don't even know that multi-paragraph help even exists in Rust apps. (Admittedly git has different -h and --help, but I don't especially like that either.)

Expected Behaviour

Either don't strip trailing periods from doc comments by default, or add a struct-wide or per-field option to disable stripping the trailing period. Ideally you could detect multi-sentence comments and avoid stripping the trailing period, but this may be difficult to implement without false positives or negatives.

I'm not sure how to unify the behavior of -h and --help, or address the odd formatting of --help showing 1 sentence followed by paragraphs.

Additional Context

Somewhat related discussions:

• If a help message ends in a single period the period does not show up when printed to the console TeXitoi/structopt#341 found this behavior unexpected.
• With derive, don’t include short help in long help #2247 dislikes the current long help format (1 sentence followed by a paragraph).

Debug Output

No response

[epage]

Thanks for reporting this!

#1015 already exists about -h / --help.

TeXitoi/structopt#341 has some interesting trade offs and a workaround (verbatim_doc_comment), on top of manually specifying it (help and long_help attributes). In this case, that behavior falls flat.

In this specific case

    /// If omitted, installs a shortcut to itself to the "Send To" menu.
    /// If passed, installs a shortcut to the .exe to the start menu.

Two thoughts on approaches

• This command operates in two modes. Sounds like one is user-facing for initialization and the other is used in the initialized state? I would make the documentation focus on the case users will interact with it
• Grammatically, I would put emphasis on the case where an arg is present, something like Installs a shortcut to the .exe in the start menu [default this program].

[briankung]

Hi, just adding a link to the (presumably) upstream issue: TeXitoi/structopt#341

[obskyr]

This dovetails with #3198 in an unfortunate manner. The following are true:

• There is no way to put a period at the end of a help message without using verbatim_doc_comment, and
• There is no way to escape newlines when using verbatim_doc_comment.

Together, this means that there is no way to end a help message with a period and split the doc comment across multiple lines (without also introducing manual line breaks to the help message). You essentially have to choose between having the period stripped, introducing a bunch of manual newlines into the message, or fitting the doc comment on a single line.

[zanieb]

Hi! Just want to share my use-case here — I'm wrapping Clap to generate reference documentation for my CLI and it'd be great to be able to retain periods in the website.