With derive, don’t include short help in long help

[wchargin]

My application uses #[derive(Clap)] (at 3.0.0-beta.2) and includes a
docstring with both short help text and long help text for each item.
For example:

    /// Log directory to load
    ///
    /// Directory to recursively scan for event files (files matching the `*tfevents*` glob). This
    /// directory, its descendants, and its event files will be periodically polled for new data.
    #[clap(long)]
    logdir: PathBuf,

The goal is to ensure that the help for each item shows up as a single
line when run with -h, and provides more detailed information when run
with --help. The -h view works great:

OPTIONS:
        --host <host>                          Bind to this IP address [default: ::0]
        --logdir <logdir>                      Log directory to load
        --port <port>                          Bind to this port [default: 6806]
        --port-file <port-file>                Write bound port to this file
        --reload-interval <reload-interval>    Delay between reload cycles (seconds) [default: 5]

But with --help, both the short help and the long help are shown:

        --host <host>
            Bind to this IP address
            
            IP address to bind this server to. May be an IPv4 address (e.g., 127.0.0.1 or 0.0.0.0)
            or an IPv6 address (e.g., ::1 or ::0). [default: ::0]

        --logdir <logdir>
            Log directory to load
            
            Directory to recursively scan for event files (files matching the `*tfevents*` glob).
            This directory, its descendants, and its event files will be periodically polled for new
            data.

        --port <port>
            Bind to this port
            
            Port to bind this server to. Use `0` to request an arbitrary free port from the OS.
            [default: 6806]

This causes an extra paragraph on each item, duplicates the information,
and makes it grammatically inconsistent (the short helps are fragments,
whereas the long helps are sentences/paragraphs).

It would be great if --help could show just the long help:

        --host <host>
            IP address to bind this server to. May be an IPv4 address (e.g., 127.0.0.1 or 0.0.0.0)
            or an IPv6 address (e.g., ::1 or ::0). [default: ::0]

        --logdir <logdir>
            Directory to recursively scan for event files (files matching the `*tfevents*` glob).
            This directory, its descendants, and its event files will be periodically polled for new
            data.

        --port <port>
            Port to bind this server to. Use `0` to request an arbitrary free port from the OS.
            [default: 6806]

Might we change the derive-macro syntax to strip the first paragraph
from long help when more than one paragraph is given? Or, other
suggestions to solve this problem would also be appreciated.

Alternatives: maybe an option to #[clap], in case people want the
existing behavior? maybe some way to combine the texts, by adding a full
stop if none exists and joining the first paragraph break? (sounds
confusing, though)

Make sure you completed the following tasks

• Searched the discussions
• Searched the closed issues

[wchargin]

I just spent ~10 minutes reading the code, which was enlightening. As a
beta user, I had had the following questions:

1. What exactly am I allowed to pass to the derive macro? The docs say
   that it’s less customizable, and indeed don’t show many
   customizations. Are things like arg.value_name(...) off the table?
2. How exactly does Clap determine the short and long help texts?

I now see that the answer to (1) is “you can call any method on Arg
via the derive macro like #[clap(value_name("foo"))], with a shorthand
for unary string methods as #[clap(value_name = "foo")]”. Lovely!

And it looks like the answer to (2) is “first paragraph for short
help, all paragraphs for long, but you can actually leave in the
Rustdoc-conventional period and Clap will strip it for the short text”.
So that’s nice, too!

But now I’m also a bit more convinced that there’s not currently an easy
way to do what I originally wanted in this issue. :-)

Mentioning these in case you find the early adopter feedback helpful,
not to berate for lack of docs while we’re still in beta.

[pksunkara]

You can do about = "short help text", long_about = "long help text" but clap doesn't take from the docstrings anymore.

[wchargin]

Yes, I know about this, but taking from the docstrings is a really nice
feature, so I don’t think that this really answers my question. Would
you be open to considering this as a feature request?

[pksunkara]

Sorry but no. It doesn't feel ergonomic. Because most of the time, long help involves the short help too.

The issue you are having is because you are using short help as a title instead of summary.