From 2698f04f703bfba0034c4458562700c2fc2bcdbd Mon Sep 17 00:00:00 2001 From: Ed Page Date: Fri, 16 Aug 2024 09:34:58 -0500 Subject: [PATCH] docs(complete): Specify the compatibility guarentees --- clap_complete/src/dynamic/command/mod.rs | 11 +++++++++++ clap_complete/src/dynamic/env/mod.rs | 11 +++++++++++ 2 files changed, 22 insertions(+) diff --git a/clap_complete/src/dynamic/command/mod.rs b/clap_complete/src/dynamic/command/mod.rs index 799d56b65ae3..ce3c4ffd4301 100644 --- a/clap_complete/src/dynamic/command/mod.rs +++ b/clap_complete/src/dynamic/command/mod.rs @@ -5,6 +5,13 @@ //! //! To source your completions: //! +//! **WARNING:** We recommend re-sourcing your completions on upgrade. +//! These completions work by generating shell code that calls into `your_program` while completing. +//! That interface is unstable and a mismatch between the shell code and `your_program` may result +//! in either invalid completions or no completions being generated. +//! For this reason, we recommend generating the shell code anew on shell startup so that it is +//! "self-correcting" on shell launch, rather than writing the generated completions to a file. +//! //! Bash //! ```bash //! echo "source <(your_program complete bash)" >> ~/.bashrc @@ -207,6 +214,10 @@ pub trait CommandCompleter { /// /// Write the `buf` the logic needed for calling into ` complete`, passing needed /// arguments to [`CommandCompleter::write_complete`] through the environment. + /// + /// **WARNING:** There are no stability guarantees between the call to + /// [`CommandCompleter::write_complete`] that this generates and actually calling [`CommandCompleter::write_complete`]. + /// Caching the results of this call may result in invalid or no completions to be generated. fn write_registration( &self, name: &str, diff --git a/clap_complete/src/dynamic/env/mod.rs b/clap_complete/src/dynamic/env/mod.rs index be736e759b56..91612d865a74 100644 --- a/clap_complete/src/dynamic/env/mod.rs +++ b/clap_complete/src/dynamic/env/mod.rs @@ -18,6 +18,13 @@ //! //! To source your completions: //! +//! **WARNING:** We recommend re-sourcing your completions on upgrade. +//! These completions work by generating shell code that calls into `your_program` while completing. +//! That interface is unstable and a mismatch between the shell code and `your_program` may result +//! in either invalid completions or no completions being generated. +//! For this reason, we recommend generating the shell code anew on shell startup so that it is +//! "self-correcting" on shell launch, rather than writing the generated completions to a file. +//! //! Bash //! ```bash //! echo "source <(COMPLETE=bash your_program)" >> ~/.bashrc @@ -271,6 +278,10 @@ pub trait EnvCompleter { /// /// Write the `buf` the logic needed for calling into `= --`, passing needed /// arguments to [`EnvCompleter::write_complete`] through the environment. + /// + /// **WARNING:** There are no stability guarantees between the call to + /// [`CommandCompleter::write_complete`] that this generates and actually calling [`CommandCompleter::write_complete`]. + /// Caching the results of this call may result in invalid or no completions to be generated. fn write_registration( &self, var: &str,