Skip to content

Commit

Permalink
Merge pull request #250 from lafrenierejm/normalize-docstrings
Browse files Browse the repository at this point in the history 
Normalize docstrings
  • Loading branch information
@phiresky
phiresky authored Oct 8, 2024
2 parents 6b79490 + c5dd740 commit dcbcb71
Show file tree
Hide file tree
Showing 2 changed files with 66 additions and 52 deletions.
44 changes: 30 additions & 14 deletions src/adapters/custom.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,32 +25,48 @@ use tokio_util::io::StreamReader;
// mostly the same as AdapterMeta + SpawningFileAdapter
#[derive(Debug, Deserialize, Serialize, JsonSchema, Default, PartialEq, Clone)]
pub struct CustomAdapterConfig {
/// the unique identifier and name of this adapter. Must only include a-z, 0-9, _
/// The unique identifier and name of this adapter.
///
/// Must only include a-z, 0-9, _.
pub name: String,
/// a description of this adapter. shown in help

/// The description of this adapter shown in help.
pub description: String,
/// if true, the adapter will be disabled by default

/// If true, the adapter will be disabled by default.
pub disabled_by_default: Option<bool>,
/// version identifier. used to key cache entries, change if the configuration or program changes

/// Version identifier used to key cache entries.
///
/// Change this if the configuration or program changes.
pub version: i32,
/// the file extensions this adapter supports. For example ["epub", "mobi"]

/// The file extensions this adapter supports, for example `["epub", "mobi"]`.
pub extensions: Vec<String>,
/// if not null and --rga-accurate is enabled, mime type matching is used instead of file name matching

/// If not null and `--rga-accurate` is enabled, mimetype matching is used instead of file name matching.
pub mimetypes: Option<Vec<String>>,
/// if --rga-accurate, only match by mime types, ignore extensions completely

/// If `--rga-accurate`, only match by mime types and ignore extensions completely.
pub match_only_by_mime: Option<bool>,
/// the name or path of the binary to run

/// The name or path of the binary to run.
pub binary: String,
/// The arguments to run the program with. Placeholders:
/// - $input_file_extension: the file extension (without dot). e.g. foo.tar.gz -> gz
/// - $input_file_stem, the file name without the last extension. e.g. foo.tar.gz -> foo.tar
/// - $input_virtual_path: the full input file path. Note that this path may not actually exist on disk because it is the result of another adapter

/// The arguments to run the program with.
/// Placeholders:
/// - `$input_file_extension`: the file extension (without dot). e.g. foo.tar.gz -> gz
/// - `$input_file_stem`: the file name without the last extension. e.g. foo.tar.gz -> foo.tar
/// - `$input_virtual_path`: the full input file path.
/// Note that this path may not actually exist on disk because it is the result of another adapter.
///
/// stdin of the program will be connected to the input file, and stdout is assumed to be the converted file
pub args: Vec<String>,
/// The output path hint. The placeholders are the same as for `.args`

/// The output path hint.
/// The placeholders are the same as for `.args`
///
/// If not set, defaults to "${input_virtual_path}.txt"
/// If not set, defaults to `"${input_virtual_path}.txt"`.
///
/// Setting this is useful if the output format is not plain text (.txt) but instead some other format that should be passed to another adapter
pub output_path_hint: Option<String>,
Expand Down
74 changes: 36 additions & 38 deletions src/config.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -98,10 +98,11 @@ impl FromStr for CacheMaxBlobLen {

/// # rga configuration
///
/// this is kind of a "polyglot" struct, since it serves three functions
/// This is kind of a "polyglot" struct serving multiple purposes:
///
/// 1. describing the command line arguments using structopt+clap and for man page / readme generation
/// 2. describing the config file format (output as JSON schema via schemars)
/// 1. Declare the command line arguments using structopt+clap
/// 1. Provide information for manpage / readme generation.
/// 1. Describe the config file format (output as JSON schema via schemars).
#[derive(StructOpt, Debug, Deserialize, Serialize, JsonSchema, Default, Clone)]
#[structopt(
name = "ripgrep-all",
Expand All @@ -114,23 +115,21 @@ impl FromStr for CacheMaxBlobLen {
usage = "rga [RGA OPTIONS] [RG OPTIONS] PATTERN [PATH ...]"
)]
pub struct RgaConfig {
/// Use more accurate but slower matching by mime type
/// Use more accurate but slower matching by mime type.
///
/// By default, rga will match files using file extensions.
/// Some programs, such as sqlite3, don't care about the file extension at all,
/// so users sometimes use any or no extension at all. With this flag, rga
/// will try to detect the mime type of input files using the magic bytes
/// (similar to the `file` utility), and use that to choose the adapter.
/// Some programs, such as sqlite3, don't care about the file extension at all, so users sometimes use any or no extension at all.
/// With this flag, rga will try to detect the mime type of input files using the magic bytes (similar to the `file` utility), and use that to choose the adapter.
/// Detection is only done on the first 8KiB of the file, since we can't always seek on the input (in archives).
#[serde(default, skip_serializing_if = "is_default")]
#[structopt(long = "--rga-accurate")]
pub accurate: bool,

/// Change which adapters to use and in which priority order (descending)
/// Change which adapters to use and in which priority order (descending).
///
/// "foo,bar" means use only adapters foo and bar.
/// "-bar,baz" means use all default adapters except for bar and baz.
/// "+bar,baz" means use all default adapters and also bar and baz.
/// - "foo,bar" means use only adapters foo and bar.
/// - "-bar,baz" means use all default adapters except for bar and baz.
/// - "+bar,baz" means use all default adapters and also bar and baz.
#[serde(default, skip_serializing_if = "is_default")]
#[structopt(
long = "--rga-adapters",
Expand All @@ -143,7 +142,7 @@ pub struct RgaConfig {
#[structopt(flatten)]
pub cache: CacheConfig,

/// Maximum nestedness of archives to recurse into
/// Maximum depth of nested archives to recurse into.
///
/// When searching in archives, rga will recurse into archives inside archives.
/// This option limits the depth.
Expand All @@ -164,63 +163,62 @@ pub struct RgaConfig {
#[structopt(long = "--rga-no-prefix-filenames")]
pub no_prefix_filenames: bool,

//////////////////////////////////////////
//////////////////////////// Config file only
//////////////////////////////////////////
#[serde(default, skip_serializing_if = "is_default")]
#[structopt(skip)]
#[structopt(skip)] // config file only
pub custom_adapters: Option<Vec<CustomAdapterConfig>>,
//////////////////////////////////////////
//////////////////////////// CMD line only
//////////////////////////////////////////

#[serde(skip)]
#[structopt(long = "--rga-config-file", require_equals = true)]
pub config_file_path: Option<String>,

/// same as passing path directly, except if argument is empty
/// kinda hacky, but if no file is found, fzf calls rga with empty string as path, which causes No such file or directory from rg. So filter those cases and return specially
#[serde(skip)]
/// Same as passing path directly, except if argument is empty.
///
/// Kinda hacky, but if no file is found, `fzf` calls `rga` with empty string as path, which causes "No such file or directory from rg".
/// So filter those cases and return specially.
#[serde(skip)] // CLI only
#[structopt(long = "--rga-fzf-path", require_equals = true, hidden = true)]
pub fzf_path: Option<String>,

// these arguments are basically "subcommands" that stop the process, so don't serialize them
#[serde(skip)]
#[serde(skip)] // CLI only
#[structopt(long = "--rga-list-adapters", help = "List all known adapters")]
pub list_adapters: bool,

#[serde(skip)]
#[serde(skip)] // CLI only
#[structopt(
long = "--rga-print-config-schema",
help = "Print the JSON Schema of the configuration file"
)]
pub print_config_schema: bool,

#[serde(skip)]
#[serde(skip)] // CLI only
#[structopt(long, help = "Show help for ripgrep itself")]
pub rg_help: bool,

#[serde(skip)]
#[serde(skip)] // CLI only
#[structopt(long, help = "Show version of ripgrep itself")]
pub rg_version: bool,
}

#[derive(StructOpt, Debug, Deserialize, Serialize, JsonSchema, Default, Clone, PartialEq)]
pub struct CacheConfig {
/// Disable caching of results
/// Disable caching of results.
///
/// By default, rga caches the extracted text, if it is small enough,
/// to a database in ${XDG_CACHE_DIR-~/.cache}/ripgrep-all on Linux,
/// ~/Library/Caches/ripgrep-all on macOS,
/// or C:\Users\username\AppData\Local\ripgrep-all on Windows.
/// By default, rga caches the extracted text, if it is small enough, to a database.
/// This way, repeated searches on the same set of files will be much faster.
/// The location of the DB varies by platform:
/// - `${XDG_CACHE_DIR-~/.cache}/ripgrep-all` on Linux
/// - `~/Library/Caches/ripgrep-all` on macOS
/// - `C:\Users\username\AppData\Local\ripgrep-all` on Windows
///
/// If you pass this flag, all caching will be disabled.
#[serde(default, skip_serializing_if = "is_default")]
#[structopt(long = "--rga-no-cache")]
pub disabled: bool,

/// Max compressed size to cache
/// Max compressed size to cache.
///
/// Longest byte length (after compression) to store in cache. Longer adapter outputs will not be cached and recomputed every time.
/// Longest byte length (after compression) to store in cache.
/// Longer adapter outputs will not be cached and recomputed every time.
///
/// Allowed suffixes on command line: k M G
#[serde(default, skip_serializing_if = "is_default")]
Expand All @@ -233,9 +231,9 @@ pub struct CacheConfig {
)]
pub max_blob_len: CacheMaxBlobLen,

/// ZSTD compression level to apply to adapter outputs before storing in cache db
/// ZSTD compression level to apply to adapter outputs before storing in cache DB.
///
/// Ranges from 1 - 22
/// Ranges from 1 - 22.
#[serde(default, skip_serializing_if = "is_default")]
#[structopt(
default_value,
Expand All @@ -246,7 +244,7 @@ pub struct CacheConfig {
)]
pub compression_level: CacheCompressionLevel,

/// Path to store cache db
/// Path to store cache DB.
#[serde(default, skip_serializing_if = "is_default")]
#[structopt(
default_value,
Expand Down

0 comments on commit dcbcb71

Please sign in to comment.