From 971b6b683e4823cad5e1af68fc5216de45f912e9 Mon Sep 17 00:00:00 2001 From: Richard Maw Date: Mon, 11 Oct 2021 22:08:51 +0100 Subject: [PATCH] fixup! Move explanatory text from examples to docstring --- clap_derive/examples/hostname.rs | 21 +--------------- examples/24_multicall_busybox.rs | 14 +---------- src/build/app/settings.rs | 43 ++++++++++++++++++++++++++------ 3 files changed, 37 insertions(+), 41 deletions(-) diff --git a/clap_derive/examples/hostname.rs b/clap_derive/examples/hostname.rs index 43ce82453fa..42d650a70a8 100644 --- a/clap_derive/examples/hostname.rs +++ b/clap_derive/examples/hostname.rs @@ -1,25 +1,6 @@ //! Example of `hostname`-style multicall program //! -//! `hostname` is a command to just output the configured hostname. -//! It may also render other network-address related information -//! if linked to under a different name -//! e.g. `dnsdomainname` for the domain name part of the FQDN. -//! -//! `hostname`-style differs from `busybox`-style in that the applets -//! should not ever be available as a subcommand -//! and the name of the executable is the same as an applet. -//! -//! i.e. `hostname` doesn't have a `dnsdomainname` subcommand, -//! `dnsdomainname` must only be run via a soft or hard link to the executable. -//! -//! This behaviour is opted-into by naming an applet subcommand -//! the same as the program name. -//! -//! This is desirable when the executable has a primary purpose -//! rather than being a collection of varied applets, -//! so it is appropriate to name the executable after its purpose, -//! but there is other related functionality that would be convenient to provide -//! and it is convenient for the code to implement it to be in the same executable. +//! See the documentation for clap::AppSettings::Multicall for rationale. //! //! This example omits the implementation of displaying address config. diff --git a/examples/24_multicall_busybox.rs b/examples/24_multicall_busybox.rs index 6a3e61e312d..8c4429e3504 100644 --- a/examples/24_multicall_busybox.rs +++ b/examples/24_multicall_busybox.rs @@ -1,18 +1,6 @@ //! Example of a `busybox-style` multicall program //! -//! `busybox` is a single executable that contains a variety of applets -//! for a fully functional Linux userland. -//! -//! `busybox`-style differs from `hostname`-style in that there is a launcher program -//! which the applets are available as subcommands. -//! i.e. you can use the `cat` command either as a link named `cat` -//! or as `busybox cat`. -//! -//! This behaviour is opted-into by not naming an applet the same as the main program. -//! -//! This is desirable when the launcher program has additional options -//! or it is useful to run the applet without installing a symlink -//! e.g. for testing purposes, or there may already be a command of that name installed. +//! See the documentation for clap::AppSettings::Multicall for rationale. //! //! This example omits every command except true and false, //! which are the most trivial to implement, diff --git a/src/build/app/settings.rs b/src/build/app/settings.rs index 78c3f5119ac..3dd485a24c9 100644 --- a/src/build/app/settings.rs +++ b/src/build/app/settings.rs @@ -651,12 +651,19 @@ pub enum AppSettings { /// Parse the bin name (argv[0]) as a subcommand /// - /// Busybox is a common example of a "multicall" executable - /// where the command `cat` is a link to the `busybox` bin - /// and, when `cat` is run, `busybox` acts is if you ran `busybox cat`. + /// This adds a small performance penalty to startup + /// as it requires comparing the bin name against every subcommand name. + /// + /// A "multicall" executable is a single executable + /// that contains a variety of applets, + /// and decides which applet to run based on the name of the file. + /// The executable can be called from different names by creating hard links + /// or symbolic links to it. /// - /// This adds a small performance penalty to startup compared to subcommands - /// for comparing argv[0] against applet names. + /// This is desirable when it is convenient to store code + /// for many programs in the same file, + /// such as deduplicating code across multiple programs + /// without loading a shared library at runtime. /// /// Multicall can't be used with [`NoBinaryName`] since they interpret /// the command name in incompatible ways. @@ -666,6 +673,16 @@ pub enum AppSettings { /// Multicall applets are defined as subcommands /// to an app which has the Multicall setting enabled. /// + /// Busybox is a common example of a "multicall" executable + /// with a subcommmand for each applet that can be run directly, + /// e.g. with the `cat` applet being run by running `busybox cat`, + /// or with `cat` as a link to the `busybox` binary. + /// + /// This is desirable when the launcher program has additional options + /// or it is useful to run the applet without installing a symlink + /// e.g. to test the applet without installing it + /// or there may already be a command of that name installed. + /// /// ```rust /// # use clap::{App, AppSettings}; /// let mut app = App::new("busybox") @@ -681,9 +698,19 @@ pub enum AppSettings { /// assert_eq!(m.subcommand_name(), Some("true")); /// ``` /// - /// If the name of an applet is the name of the command, - /// the applet's name is matched - /// and subcommands may not be provided to select another applet. + /// `hostname` is another example of a multicall executable. + /// It differs from busybox by not supporting running applets via subcommand + /// and is instead only runnable via links. + /// + /// This is desirable when the executable has a primary purpose + /// rather than being a collection of varied applets, + /// so it is appropriate to name the executable after its purpose, + /// but there is other related functionality that would be convenient to provide + /// and it is convenient for the code to implement it to be in the same executable. + /// + /// This behaviour can be opted-into + /// by naming a subcommand with the same as the program + /// as applet names take priority. /// /// ```rust /// # use clap::{App, AppSettings, ErrorKind};