Skip to content

Commit

Permalink
Merge pull request #5680 from epage/unstable
Browse files Browse the repository at this point in the history
docs(complete): Specify the compatibility guarentees
  • Loading branch information
epage authored Aug 16, 2024
2 parents 23fb056 + b2c3126 commit 17d6d24
Show file tree
Hide file tree
Showing 2 changed files with 22 additions and 0 deletions.
11 changes: 11 additions & 0 deletions clap_complete/src/dynamic/command/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -207,6 +214,10 @@ pub trait CommandCompleter {
///
/// Write the `buf` the logic needed for calling into `<cmd> 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,
Expand Down
11 changes: 11 additions & 0 deletions clap_complete/src/dynamic/env/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -276,6 +283,10 @@ pub trait EnvCompleter {
///
/// Write the `buf` the logic needed for calling into `<VAR>=<shell> <cmd> --`, passing needed
/// arguments to [`EnvCompleter::write_complete`] through the environment.
///
/// **WARNING:** There are no stability guarantees between the call to
/// [`EnvCompleter::write_complete`] that this generates and actually calling [`EnvCompleter::write_complete`].
/// Caching the results of this call may result in invalid or no completions to be generated.
fn write_registration(
&self,
var: &str,
Expand Down

0 comments on commit 17d6d24

Please sign in to comment.