Inconsistency in showing command description when using about

[teamplayer3]

Please complete the following tasks

• I have searched the discussions
• I have searched the open and rejected issues

Rust Version

rustc 1.82.0-nightly (f167efad2 2024-08-24)

Clap Version

4.5.18

Minimal reproducible code

[package]
name = "clap-bug"
version = "0.1.0"
edition = "2021"

description = """
This is from about section.
"""

[dependencies]
clap = { version = "4.5.18", features = ["derive"] }

use clap::{Args, Parser};

#[derive(Parser, Debug)]
#[command(version, about)]
pub struct Cli {
    #[command(subcommand)]
    pub command: CargoInvocation,
}

#[derive(Parser, Debug)]
pub enum CargoInvocation {
    #[command(name = "a-cmd", about)]
    A(A),
    /// This is a test.
    #[command(name = "b-cmd")]
    B(B),
}

#[derive(Args, Debug)]
pub struct A {}

#[derive(Args, Debug)]
pub struct B {}

fn main() {
    let args = Cli::parse();
}

Steps to reproduce the bug with the above code

cargo run -- --help

Actual Behaviour

This is from about section.


Usage: clap-bug.exe <COMMAND>

Commands:
  a-cmd  This is from about section.

  b-cmd  This is a test
  help   Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

Expected Behaviour

The . at the command description of a-cmd should get removed, as with the other descriptions.

This is from about section.


Usage: clap-bug.exe <COMMAND>

Commands:
  a-cmd  This is from about section

  b-cmd  This is a test
  help   Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

Additional Context

No response

Debug Output

[clap_builder::builder::command]Command::_do_parse
[clap_builder::builder::command]Command::_build: name="clap-bug"
[clap_builder::builder::command]Command::_propagate:clap-bug
[clap_builder::builder::command]Command::_check_help_and_version:clap-bug expand_help_tree=false
[clap_builder::builder::command]Command::long_help_exists
[clap_builder::builder::command]Command::_check_help_and_version: Building default --help
[clap_builder::builder::command]Command::_check_help_and_version: Building default --version
[clap_builder::builder::command]Command::_check_help_and_version: Building help subcommand
[clap_builder::builder::command]Command::_propagate_global_args:clap-bug
[clap_builder::builder::debug_asserts]Command::_debug_asserts
[clap_builder::builder::debug_asserts]Arg::_debug_asserts:help
[clap_builder::builder::debug_asserts]Arg::_debug_asserts:version
[clap_builder::builder::debug_asserts]Command::_verify_positionals
[clap_builder::parser::parser]Parser::get_matches_with
[clap_builder::parser::parser]Parser::get_matches_with: Begin parsing '"--help"'
[clap_builder::parser::parser]Parser::possible_subcommand: arg=Ok("--help")
[clap_builder::parser::parser]Parser::get_matches_with: sc=None
[clap_builder::parser::parser]Parser::parse_long_arg
[clap_builder::parser::parser]Parser::parse_long_arg: Does it contain '='...
[clap_builder::parser::parser]Parser::parse_long_arg: Found valid arg or flag '--help'
[clap_builder::parser::parser]Parser::parse_long_arg("help"): Presence validated
[clap_builder::parser::parser]Parser::react action=Help, identifier=Some(Long), source=CommandLine
[clap_builder::parser::parser]Help: use_long=true
[clap_builder::builder::command]Command::long_help_exists: false
[clap_builder::builder::command]Command::write_help_err: clap-bug, use_long=false
[clap_builder::builder::command]Command::long_help_exists: false
[  clap_builder::output::help]write_help
[clap_builder::output::help_template]HelpTemplate::new cmd=clap-bug, use_long=false
[clap_builder::output::help_template]should_show_arg: use_long=false, arg=help
[clap_builder::output::help_template]HelpTemplate::write_templated_help
[clap_builder::output::help_template]HelpTemplate::write_before_help
[ clap_builder::output::usage]Usage::create_usage_no_title
[ clap_builder::output::usage]Usage::create_usage_no_title
[ clap_builder::output::usage]Usage::write_help_usage
[ clap_builder::output::usage]Usage::write_arg_usage; incl_reqs=true
[ clap_builder::output::usage]Usage::needs_options_tag
[ clap_builder::output::usage]Usage::needs_options_tag:iter: f=help
[ clap_builder::output::usage]Usage::needs_options_tag:iter Option is built-in
[ clap_builder::output::usage]Usage::needs_options_tag:iter: f=version
[ clap_builder::output::usage]Usage::needs_options_tag:iter Option is built-in
[ clap_builder::output::usage]Usage::needs_options_tag: [OPTIONS] not required
[ clap_builder::output::usage]Usage::write_args: incls=[]
[ clap_builder::output::usage]Usage::get_args: unrolled_reqs=[]
[ clap_builder::output::usage]Usage::write_subcommand_usage
[ clap_builder::output::usage]Usage::create_usage_no_title: usage=clap-bug.exe <COMMAND>
[clap_builder::output::help_template]HelpTemplate::write_all_args
[clap_builder::output::help_template]should_show_arg: use_long=false, arg=help
[clap_builder::output::help_template]should_show_arg: use_long=false, arg=version
[clap_builder::output::help_template]HelpTemplate::write_subcommands
[clap_builder::output::help_template]HelpTemplate::write_subcommands longest = 5
[clap_builder::output::help_template]HelpTemplate::sc_spec_vals: a=a-cmd
[clap_builder::output::help_template]HelpTemplate::sc_spec_vals: a=b-cmd
[clap_builder::output::help_template]HelpTemplate::sc_spec_vals: a=help
[clap_builder::output::help_template]HelpTemplate::write_subcommand
[clap_builder::output::help_template]HelpTemplate::sc_spec_vals: a=a-cmd
[clap_builder::output::help_template]HelpTemplate::help
[clap_builder::output::help_template]HelpTemplate::help: help_width=9, spaces=27, avail=91
[clap_builder::output::help_template]HelpTemplate::write_subcommand
[clap_builder::output::help_template]HelpTemplate::sc_spec_vals: a=b-cmd
[clap_builder::output::help_template]HelpTemplate::help
[clap_builder::output::help_template]HelpTemplate::help: help_width=9, spaces=14, avail=91
[clap_builder::output::help_template]HelpTemplate::write_subcommand
[clap_builder::output::help_template]HelpTemplate::sc_spec_vals: a=help
[clap_builder::output::help_template]HelpTemplate::help
[clap_builder::output::help_template]HelpTemplate::help: help_width=9, spaces=57, avail=91
[clap_builder::output::help_template]HelpTemplate::write_args Options
[clap_builder::output::help_template]should_show_arg: use_long=false, arg=help
[clap_builder::output::help_template]HelpTemplate::write_args: arg="help" longest=6
[clap_builder::output::help_template]should_show_arg: use_long=false, arg=version
[clap_builder::output::help_template]HelpTemplate::write_args: arg="version" longest=9
[clap_builder::output::help_template]should_show_arg: use_long=false, arg=help
[clap_builder::output::help_template]HelpTemplate::spec_vals: a=--help
[clap_builder::output::help_template]should_show_arg: use_long=false, arg=version
[clap_builder::output::help_template]HelpTemplate::spec_vals: a=--version
[clap_builder::output::help_template]HelpTemplate::spec_vals: a=--help
[clap_builder::output::help_template]HelpTemplate::short
[clap_builder::output::help_template]HelpTemplate::long
[clap_builder::output::help_template]HelpTemplate::align_to_about: arg=help, next_line_help=false, longest=9
[clap_builder::output::help_template]HelpTemplate::align_to_about: positional=false arg_len=6, spaces=5
[clap_builder::output::help_template]HelpTemplate::help
[clap_builder::output::help_template]HelpTemplate::help: help_width=17, spaces=10, avail=83
[clap_builder::output::help_template]HelpTemplate::spec_vals: a=--version
[clap_builder::output::help_template]HelpTemplate::short
[clap_builder::output::help_template]HelpTemplate::long
[clap_builder::output::help_template]HelpTemplate::align_to_about: arg=version, next_line_help=false, longest=9
[clap_builder::output::help_template]HelpTemplate::align_to_about: positional=false arg_len=9, spaces=2
[clap_builder::output::help_template]HelpTemplate::help
[clap_builder::output::help_template]HelpTemplate::help: help_width=17, spaces=13, avail=83
[clap_builder::output::help_template]HelpTemplate::write_after_help
[clap_builder::builder::command]Command::color: Color setting...
[clap_builder::builder::command]Auto
[clap_builder::builder::command]Command::color: Color setting...
[clap_builder::builder::command]Auto

[epage]

Yes, pulling from the env variable takes it literally for the about

clap/clap_derive/src/item.rs

Lines 517 to 521 in 1c0e602

	if let Some(method) =
	Method::from_env(attr.name.clone(), "CARGO_PKG_DESCRIPTION")?
	{
	self.methods.push(method);
	}

The builder equivalent also doesn't do anything special

clap/clap_builder/src/macros.rs

Lines 60 to 78 in 1c0e602

	/// Allows you to pull the description from your Cargo.toml at compile time.
	///
	/// # Examples
	///
	/// ```no_run
	/// # use clap_builder as clap;
	/// # use clap::crate_description;
	/// # use clap::Command;
	/// let m = Command::new("cmd")
	/// .about(crate_description!())
	/// .get_matches();
	/// ```
	#[cfg(feature = "cargo")]
	#[macro_export]
	macro_rules! crate_description {
	() => {
	env!("CARGO_PKG_DESCRIPTION")
	};
	}

While we always remove the period when extracting an about from doc comments

clap/clap_derive/src/utils/doc_comments.rs

Lines 71 to 79 in 1c0e602

	let (short, long) = if preprocess {
	let short = merge_lines(lines);
	let long = force_long.then(|| short.clone());
	let short = remove_period(short);
	(short, long)
	} else {
	let short = lines.join("\n");
	let long = force_long.then(|| short.clone());
	(short, long)

doc comments also have us trim later paragraphs.

I'm also curious what common conventions are for each and how changing this might impact them.

[teamplayer3]

I think the more common approach is to display these descriptions without a ..