github-mirror/fish-shell
2
0
Fork 0
mirror of https://github.com/fish-shell/fish-shell.git synced 2024-11-22 12:41:08 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Replace C++ doc \return with "Return"

Browse Source 
quick_replace '\\\\return(s)? ' 'Return$1 ' src/

Filtered to only lines beginning with //
This commit is contained in:
Mahmoud Al-Qudsi 2024-05-06 14:58:10 -05:00
parent 589639a87d
commit 5f8f799cf7
52 changed files with 289 additions and 289 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
src/abbrs.rs
View File

@ -92,12 +92,12 @@ impl Abbreviation {
}
}
// \return true if this is a regex abbreviation.
// Return true if this is a regex abbreviation.
pub fn is_regex(&self) -> bool {
self.regex.is_some()
}
// \return true if we match a token at a given position.
// Return true if we match a token at a given position.
pub fn matches(&self, token: &wstr, position: Position, command: &wstr) -> bool {
if !self.matches_position(position) {
return false;
@ -115,7 +115,7 @@ impl Abbreviation {
}
}
// \return if we expand in a given position.
// Return if we expand in a given position.
fn matches_position(&self, position: Position) -> bool {
return self.position == Position::Anywhere || self.position == position;
}
@ -183,7 +183,7 @@ pub struct AbbreviationSet {
}
impl AbbreviationSet {
/// \return the list of replacers for an input token, in priority order.
/// Return the list of replacers for an input token, in priority order.
/// The `position` is given to describe where the token was found.
pub fn r#match(&self, token: &wstr, position: Position, cmd: &wstr) -> Vec<Replacer> {
let mut result = vec![];
@ -201,7 +201,7 @@ impl AbbreviationSet {
return result;
}
/// \return whether we would have at least one replacer for a given token.
/// Return whether we would have at least one replacer for a given token.
pub fn has_match(&self, token: &wstr, position: Position, cmd: &wstr) -> bool {
self.abbrs
.iter()
@ -243,7 +243,7 @@ impl AbbreviationSet {
}
/// Erase an abbreviation by name.
/// \return true if erased, false if not found.
/// Return true if erased, false if not found.
pub fn erase(&mut self, name: &wstr) -> bool {
let erased = self.used_names.remove(name);
if !erased {
@ -258,18 +258,18 @@ impl AbbreviationSet {
panic!("Unable to find named abbreviation");
}
/// \return true if we have an abbreviation with the given name.
/// Return true if we have an abbreviation with the given name.
pub fn has_name(&self, name: &wstr) -> bool {
self.used_names.contains(name)
}
/// \return a reference to the abbreviation list.
/// Return a reference to the abbreviation list.
pub fn list(&self) -> &[Abbreviation] {
&self.abbrs
}
}
/// \return the list of replacers for an input token, in priority order, using the global set.
/// Return the list of replacers for an input token, in priority order, using the global set.
/// The `position` is given to describe where the token was found.
pub fn abbrs_match(token: &wstr, position: Position, cmd: &wstr) -> Vec<Replacer> {
with_abbrs(|set| set.r#match(token, position, cmd))

68
src/ast.rs
View File

@ -108,7 +108,7 @@ pub trait Node: Acceptor + ConcreteNode + std::fmt::Debug {
/// The category of this node.
fn category(&self) -> Category;
/// \return a helpful string description of this node.
/// Return a helpful string description of this node.
fn describe(&self) -> WString {
let mut res = ast_type_to_string(self.typ()).to_owned();
if let Some(n) = self.as_token() {
@ -121,21 +121,21 @@ pub trait Node: Acceptor + ConcreteNode + std::fmt::Debug {
res
}
/// \return the source range for this node, or none if unsourced.
/// Return the source range for this node, or none if unsourced.
/// This may return none if the parse was incomplete or had an error.
fn try_source_range(&self) -> Option<SourceRange>;
/// \return the source range for this node, or an empty range {0, 0} if unsourced.
/// Return the source range for this node, or an empty range {0, 0} if unsourced.
fn source_range(&self) -> SourceRange {
self.try_source_range().unwrap_or(SourceRange::new(0, 0))
}
/// \return the source code for this node, or none if unsourced.
/// Return the source code for this node, or none if unsourced.
fn try_source<'s>(&self, orig: &'s wstr) -> Option<&'s wstr> {
self.try_source_range().map(|r| &orig[r.start()..r.end()])
}
/// \return the source code for this node, or an empty string if unsourced.
/// Return the source code for this node, or an empty string if unsourced.
fn source<'s>(&self, orig: &'s wstr) -> &'s wstr {
self.try_source(orig).unwrap_or_default()
}
@ -408,7 +408,7 @@ pub trait Token: Leaf {
fn token_type(&self) -> ParseTokenType;
fn token_type_mut(&mut self) -> &mut ParseTokenType;
fn allowed_tokens(&self) -> &'static [ParseTokenType];
/// \return whether a token type is allowed in this token_t, i.e. is a member of our Toks list.
/// Return whether a token type is allowed in this token_t, i.e. is a member of our Toks list.
fn allows_token(&self, token_type: ParseTokenType) -> bool {
self.allowed_tokens().contains(&token_type)
}
@ -429,11 +429,11 @@ pub trait List: Node {
type ContentsNode: Node + Default;
fn contents(&self) -> &[Box<Self::ContentsNode>];
fn contents_mut(&mut self) -> &mut Vec<Box<Self::ContentsNode>>;
/// \return our count.
/// Return our count.
fn count(&self) -> usize {
self.contents().len()
}
/// \return whether we are empty.
/// Return whether we are empty.
fn is_empty(&self) -> bool {
self.contents().is_empty()
}
@ -2032,7 +2032,7 @@ impl CheckParse for KeywordTime {
}
impl DecoratedStatement {
/// \return the decoration for this statement.
/// Return the decoration for this statement.
pub fn decoration(&self) -> StatementDecoration {
let Some(decorator) = &self.opt_decoration else {
return StatementDecoration::none;
@ -2105,17 +2105,17 @@ impl ArgumentOrRedirectionVariant {
}
impl ArgumentOrRedirection {
/// \return whether this represents an argument.
/// Return whether this represents an argument.
pub fn is_argument(&self) -> bool {
matches!(*self.contents, ArgumentOrRedirectionVariant::Argument(_))
}
/// \return whether this represents a redirection
/// Return whether this represents a redirection
pub fn is_redirection(&self) -> bool {
matches!(*self.contents, ArgumentOrRedirectionVariant::Redirection(_))
}
/// \return this as an argument, assuming it wraps one.
/// Return this as an argument, assuming it wraps one.
pub fn argument(&self) -> &Argument {
match *self.contents {
ArgumentOrRedirectionVariant::Argument(ref arg) => arg,
@ -2123,7 +2123,7 @@ impl ArgumentOrRedirection {
}
}
/// \return this as an argument, assuming it wraps one.
/// Return this as an argument, assuming it wraps one.
pub fn redirection(&self) -> &Redirection {
match *self.contents {
ArgumentOrRedirectionVariant::Redirection(ref arg) => arg,
@ -2361,7 +2361,7 @@ impl BlockStatementHeaderVariant {
}
}
/// \return a string literal name for an ast type.
/// Return a string literal name for an ast type.
pub fn ast_type_to_string(t: Type) -> &'static wstr {
match t {
Type::token_base => L!("token_base"),
@ -2494,23 +2494,23 @@ impl Ast {
) -> Self {
parse_from_top(src, flags, out_errors, Type::freestanding_argument_list)
}
/// \return a traversal, allowing iteration over the nodes.
/// Return a traversal, allowing iteration over the nodes.
pub fn walk(&'_ self) -> Traversal<'_> {
Traversal::new(self.top.as_node())
}
/// \return the top node. This has the type requested in the 'parse' method.
/// Return the top node. This has the type requested in the 'parse' method.
pub fn top(&self) -> &dyn Node {
self.top.as_node()
}
fn top_mut(&mut self) -> &mut dyn NodeMut {
&mut *self.top
}
/// \return whether any errors were encountered during parsing.
/// Return whether any errors were encountered during parsing.
pub fn errored(&self) -> bool {
self.any_error
}
/// \return a textual representation of the tree.
/// Return a textual representation of the tree.
/// Pass the original source as `orig`.
pub fn dump(&self, orig: &wstr) -> WString {
let mut result = WString::new();
@ -2563,7 +2563,7 @@ impl Ast {
}
}
// \return the depth of a node, i.e. number of parent links.
// Return the depth of a node, i.e. number of parent links.
fn get_depth(node: &dyn Node) -> usize {
let mut result = 0;
let mut cursor = node;
@ -2648,7 +2648,7 @@ impl<'a> TokenStream<'a> {
}
}
/// \return the token at the given index, without popping it. If the token stream is exhausted,
/// Return the token at the given index, without popping it. If the token stream is exhausted,
/// it will have parse_token_type_t::terminate. idx = 0 means the next token, idx = 1 means the
/// next-next token, and so forth.
/// We must have that idx < kMaxLookahead.
@ -2677,7 +2677,7 @@ impl<'a> TokenStream<'a> {
idx % Self::MAX_LOOKAHEAD
}
/// \return the next parse token from the tokenizer.
/// Return the next parse token from the tokenizer.
/// This consumes and stores comments.
fn next_from_tok(&mut self) -> ParseToken {
loop {
@ -2690,7 +2690,7 @@ impl<'a> TokenStream<'a> {
}
}
/// \return a new parse token, advancing the tokenizer.
/// Return a new parse token, advancing the tokenizer.
/// This returns comments.
fn advance_1(&mut self) -> ParseToken {
let Some(token) = self.tok.next() else {
@ -3108,7 +3108,7 @@ impl<'s> Populator<'s> {
self.depth * 2
}
/// \return the parser's status.
/// Return the parser's status.
fn status(&mut self) -> ParserStatus {
if self.unwinding {
ParserStatus::unwinding
@ -3121,7 +3121,7 @@ impl<'s> Populator<'s> {
}
}
/// \return whether any leaf nodes we visit should be marked as unsourced.
/// Return whether any leaf nodes we visit should be marked as unsourced.
fn unsource_leaves(&mut self) -> bool {
matches!(
self.status(),
@ -3129,12 +3129,12 @@ impl<'s> Populator<'s> {
)
}
/// \return whether we permit an incomplete parse tree.
/// Return whether we permit an incomplete parse tree.
fn allow_incomplete(&self) -> bool {
self.flags.contains(ParseTreeFlags::LEAVE_UNTERMINATED)
}
/// \return whether a list type `type` allows arbitrary newlines in it.
/// Return whether a list type `type` allows arbitrary newlines in it.
fn list_type_chomps_newlines(&self, typ: Type) -> bool {
match typ {
Type::argument_list => {
@ -3187,7 +3187,7 @@ impl<'s> Populator<'s> {
}
}
/// \return whether a list type `type` allows arbitrary semicolons in it.
/// Return whether a list type `type` allows arbitrary semicolons in it.
fn list_type_chomps_semis(&self, typ: Type) -> bool {
match typ {
Type::argument_list => {
@ -3258,25 +3258,25 @@ impl<'s> Populator<'s> {
}
}
/// \return whether a list type should recover from errors.s
/// Return whether a list type should recover from errors.s
/// That is, whether we should stop unwinding when we encounter this type.
fn list_type_stops_unwind(&self, typ: Type) -> bool {
typ == Type::job_list && self.flags.contains(ParseTreeFlags::CONTINUE_AFTER_ERROR)
}
/// \return a reference to a non-comment token at index `idx`.
/// Return a reference to a non-comment token at index `idx`.
fn peek_token(&mut self, idx: usize) -> &ParseToken {
self.tokens.peek(idx)
}
/// \return the type of a non-comment token.
/// Return the type of a non-comment token.
fn peek_type(&mut self, idx: usize) -> ParseTokenType {
self.peek_token(idx).typ
}
/// Consume the next token, chomping any comments.
/// It is an error to call this unless we know there is a non-terminate token available.
/// \return the token.
/// Return the token.
fn consume_any_token(&mut self) -> ParseToken {
let tok = self.tokens.pop();
assert!(
@ -3701,7 +3701,7 @@ impl<'s> Populator<'s> {
}
/// Given a node type, allocate it and invoke its default constructor.
/// \return the resulting Node
/// Return the resulting Node
fn allocate<T: NodeMut + Default>(&self) -> Box<T> {
let result = Box::<T>::default();
FLOGF!(
@ -3717,7 +3717,7 @@ impl<'s> Populator<'s> {
// Given a node type, allocate it, invoke its default constructor,
// and then visit it as a field.
// \return the resulting Node pointer. It is never null.
// Return the resulting Node pointer. It is never null.
fn allocate_visit<T: NodeMut + Default>(&mut self) -> Box<T> {
let mut result = Box::<T>::default();
self.visit_mut(&mut *result);
@ -3927,7 +3927,7 @@ fn parse_from_top(
ast
}
/// \return tokenizer flags corresponding to parse tree flags.
/// Return tokenizer flags corresponding to parse tree flags.
impl From<ParseTreeFlags> for TokFlags {
fn from(flags: ParseTreeFlags) -> Self {
let mut tok_flags = TokFlags(0);

18
src/autoload.rs
View File

@ -82,23 +82,23 @@ impl Autoload {
assert!(removed, "cmd was not being autoloaded");
}
/// \return whether a command is currently being autoloaded.
/// Return whether a command is currently being autoloaded.
pub fn autoload_in_progress(&self, cmd: &wstr) -> bool {
self.current_autoloading.contains(cmd)
}
/// \return whether a command could potentially be autoloaded.
/// Return whether a command could potentially be autoloaded.
/// This does not actually mark the command as being autoloaded.
pub fn can_autoload(&mut self, cmd: &wstr) -> bool {
self.cache.check(cmd, true /* allow stale */).is_some()
}
/// \return whether autoloading has been attempted for a command.
/// Return whether autoloading has been attempted for a command.
pub fn has_attempted_autoload(&self, cmd: &wstr) -> bool {
self.cache.is_cached(cmd)
}
/// \return the names of all commands that have been autoloaded. Note this includes "in-flight"
/// Return the names of all commands that have been autoloaded. Note this includes "in-flight"
/// commands.
pub fn get_autoloaded_commands(&self) -> Vec<WString> {
let mut result = Vec::with_capacity(self.autoloaded_files.len());
@ -214,7 +214,7 @@ impl AutoloadFileCache {
Self::with_dirs(vec![])
}
/// \return the directories.
/// Return the directories.
fn dirs(&self) -> &[WString] {
&self.dirs
}
@ -269,24 +269,24 @@ impl AutoloadFileCache {
file
}
/// \return true if a command is cached (either as a hit or miss).
/// Return true if a command is cached (either as a hit or miss).
fn is_cached(&self, cmd: &wstr) -> bool {
self.known_files.contains_key(cmd) || self.misses_cache.contains(cmd)
}
/// \return the current timestamp.
/// Return the current timestamp.
fn current_timestamp() -> Timestamp {
Timestamp::now()
}
/// \return whether a timestamp is fresh enough to use.
/// Return whether a timestamp is fresh enough to use.
fn is_fresh(then: Timestamp, now: Timestamp) -> bool {
let seconds = now.duration_since(then).as_secs();
seconds < AUTOLOAD_STALENESS_INTERVALL
}
/// Attempt to find an autoloadable file by searching our path list for a given command.
/// \return the file, or none() if none.
/// Return the file, or none() if none.
fn locate_file(&self, cmd: &wstr) -> Option<AutoloadableFile> {
// If the command is empty or starts with NULL (i.e. is empty as a path)
// we'd try to source the *directory*, which exists.

2
src/bin/fish.rs
View File

@ -102,7 +102,7 @@ struct FishCmdOpts {
enable_private_mode: bool,
}
/// \return a timeval converted to milliseconds.
/// Return a timeval converted to milliseconds.
#[allow(clippy::unnecessary_cast)]
fn tv_to_msec(tv: &libc::timeval) -> i64 {
// milliseconds per second

14
src/bin/fish_indent.rs
View File

@ -278,7 +278,7 @@ impl<'source, 'ast> PrettyPrinterState<'source, 'ast> {
usize::try_from(self.indents[index]).unwrap()
}
// \return gap text flags for the gap text that comes *before* a given node type.
// Return gap text flags for the gap text that comes *before* a given node type.
fn gap_text_flags_before_node(&self, node: &dyn Node) -> GapFlags {
let mut result = GapFlags::default();
match node.typ() {
@ -324,12 +324,12 @@ impl<'source, 'ast> PrettyPrinterState<'source, 'ast> {
result
}
// \return whether we are at the start of a new line.
// Return whether we are at the start of a new line.
fn at_line_start(&self) -> bool {
self.output.chars().next_back().is_none_or(|c| c == '\n')
}
// \return whether we have a space before the output.
// Return whether we have a space before the output.
// This ignores escaped spaces and escaped newlines.
fn has_preceding_space(&self) -> bool {
let mut idx = isize::try_from(self.output.len()).unwrap() - 1;
@ -355,7 +355,7 @@ impl<'source, 'ast> PrettyPrinterState<'source, 'ast> {
})
}
// \return a substring of source.
// Return a substring of source.
fn substr(&self, r: SourceRange) -> &wstr {
&self.source[r.start()..r.end()]
}
@ -467,7 +467,7 @@ impl<'source, 'ast> PrettyPrinterState<'source, 'ast> {
needs_nl
}
/// \return the gap text ending at a given index into the string, or empty if none.
/// Return the gap text ending at a given index into the string, or empty if none.
fn gap_text_to(&self, end: usize) -> SourceRange {
match self.gaps.binary_search_by(|r| r.end().cmp(&end)) {
Ok(pos) => self.gaps[pos],
@ -478,7 +478,7 @@ impl<'source, 'ast> PrettyPrinterState<'source, 'ast> {
}
}
/// \return whether a range `r` overlaps an error range from our ast.
/// Return whether a range `r` overlaps an error range from our ast.
fn range_contained_error(&self, r: SourceRange) -> bool {
let errs = self.errors.as_ref().unwrap();
let range_is_before = |x: SourceRange, y: SourceRange| x.end().cmp(&y.start());
@ -727,7 +727,7 @@ impl<'source, 'ast> NodeVisitor<'_> for PrettyPrinterState<'source, 'ast> {
}
}
/// \return whether a character at a given index is escaped.
/// Return whether a character at a given index is escaped.
/// A character is escaped if it has an odd number of backslashes.
fn char_is_escaped(text: &wstr, idx: usize) -> bool {
count_preceding_backslashes(text, idx) % 2 == 1

2
src/builtins/argparse.rs
View File

@ -652,7 +652,7 @@ fn validate_arg<'opts>(
Some(retval)
}
/// \return whether the option 'opt' is an implicit integer option.
/// Return whether the option 'opt' is an implicit integer option.
fn is_implicit_int(opts: &ArgParseCmdOpts, val: &wstr) -> bool {
if opts.implicit_int_flag == '\0' {
// There is no implicit integer option.

2
src/builtins/function.rs
View File

@ -54,7 +54,7 @@ const LONG_OPTIONS: &[WOption] = &[
wopt(L!("inherit-variable"), ArgType::RequiredArgument, 'V'),
];
/// \return the internal_job_id for a pid, or None if none.
/// Return the internal_job_id for a pid, or None if none.
/// This looks through both active and finished jobs.
fn job_id_for_pid(pid: i32, parser: &Parser) -> Option<u64> {
if let Some(job) = parser.job_get_from_pid(pid) {

10
src/builtins/printf.rs
View File

@ -60,17 +60,17 @@ use crate::wutil::{
use printf_compat::args::ToArg;
use printf_compat::printf::sprintf_locale;
/// \return true if `c` is an octal digit.
/// Return true if `c` is an octal digit.
fn is_octal_digit(c: char) -> bool {
('0'..='7').contains(&c)
}
/// \return true if `c` is a decimal digit.
/// Return true if `c` is a decimal digit.
fn iswdigit(c: char) -> bool {
c.is_ascii_digit()
}
/// \return true if `c` is a hexadecimal digit.
/// Return true if `c` is a hexadecimal digit.
fn iswxdigit(c: char) -> bool {
c.is_ascii_hexdigit()
}
@ -95,11 +95,11 @@ struct builtin_printf_state_t<'a, 'b> {
locale: Locale,
}
/// Convert to a scalar type. \return the result of conversion, and the end of the converted string.
/// Convert to a scalar type. Return the result of conversion, and the end of the converted string.
/// On conversion failure, `end` is not modified.
trait RawStringToScalarType: Copy + std::convert::From<u32> {
/// Convert from a string to our self type.
/// \return the result of conversion, and the remainder of the string.
/// Return the result of conversion, and the remainder of the string.
fn raw_string_to_scalar_type<'a>(
s: &'a wstr,
locale: &Locale,

2
src/builtins/set.rs
View File

@ -380,7 +380,7 @@ struct SplitVar<'a> {
}
impl<'a> SplitVar<'a> {
/// \return the number of elements in our variable, or 0 if missing.
/// Return the number of elements in our variable, or 0 if missing.
fn varsize(&self) -> usize {
self.var.as_ref().map_or(0, |var| var.as_list().len())
}

10
src/builtins/wait.rs
View File

@ -5,12 +5,12 @@ use crate::proc::{proc_wait_any, Job};
use crate::signal::SigChecker;
use crate::wait_handle::{WaitHandleRef, WaitHandleStore};
/// \return true if we can wait on a job.
/// Return true if we can wait on a job.
fn can_wait_on_job(j: &Job) -> bool {
j.is_constructed() && !j.is_foreground() && !j.is_stopped()
}
/// \return true if a wait handle matches a pid or a process name.
/// Return true if a wait handle matches a pid or a process name.
fn wait_handle_matches(query: WaitHandleQuery, wh: &WaitHandleRef) -> bool {
match query {
WaitHandleQuery::Pid(pid) => wh.pid == pid,
@ -18,7 +18,7 @@ fn wait_handle_matches(query: WaitHandleQuery, wh: &WaitHandleRef) -> bool {
}
}
/// \return true if all chars are numeric.
/// Return true if all chars are numeric.
fn iswnumeric(s: &wstr) -> bool {
s.chars().all(|c| c.is_ascii_digit())
}
@ -31,7 +31,7 @@ enum WaitHandleQuery<'a> {
/// Walk the list of jobs, looking for a process with the given pid or proc name.
/// Append all matching wait handles to `handles`.
/// \return true if we found a matching job (even if not waitable), false if not.
/// Return true if we found a matching job (even if not waitable), false if not.
fn find_wait_handles(
query: WaitHandleQuery<'_>,
parser: &Parser,
@ -93,7 +93,7 @@ fn is_completed(wh: &WaitHandleRef) -> bool {
/// Wait for the given wait handles to be marked as completed.
/// If `any_flag` is set, wait for the first one; otherwise wait for all.
/// \return a status code.
/// Return a status code.
fn wait_for_completion(parser: &Parser, whs: &[WaitHandleRef], any_flag: bool) -> Option<c_int> {
if whs.is_empty() {
return Some(0);

10
src/common.rs
View File

@ -1096,7 +1096,7 @@ pub static EMPTY_STRING: WString = WString::new();
pub static EMPTY_STRING_LIST: Vec<WString> = vec![];
/// A function type to check for cancellation.
/// \return true if execution should cancel.
/// Return true if execution should cancel.
/// todo!("Maybe remove the box? It is only needed for get_bg_context.")
pub type CancelChecker = Box<dyn Fn() -> bool>;
@ -1258,7 +1258,7 @@ pub fn wcs2string_appending(output: &mut Vec<u8>, input: &wstr) {
});
}
/// \return the count of initial characters in `in` which are ASCII.
/// Return the count of initial characters in `in` which are ASCII.
fn count_ascii_prefix(inp: &[u8]) -> usize {
// The C++ version had manual vectorization.
inp.iter().take_while(|c| c.is_ascii()).count()
@ -1489,7 +1489,7 @@ fn can_be_encoded(wc: char) -> bool {
}
/// Call read, blocking and repeating on EINTR. Exits on EAGAIN.
/// \return the number of bytes read, or 0 on EOF, or an error.
/// Return the number of bytes read, or 0 on EOF, or an error.
pub fn read_blocked(fd: RawFd, buf: &mut [u8]) -> nix::Result<usize> {
loop {
let res = nix::unistd::read(fd, buf);
@ -2048,8 +2048,8 @@ pub trait Named {
fn name(&self) -> &'static wstr;
}
/// \return a pointer to the first entry with the given name, assuming the entries are sorted by
/// name. \return nullptr if not found.
/// Return a pointer to the first entry with the given name, assuming the entries are sorted by
/// name. Return nullptr if not found.
pub fn get_by_sorted_name<T: Named>(name: &wstr, vals: &'static [T]) -> Option<&'static T> {
match vals.binary_search_by_key(&name, |val| val.name()) {
Ok(index) => Some(&vals[index]),

2
src/complete.rs
View File

@ -276,7 +276,7 @@ impl CompletionReceiver {
}
/// Add a completion.
/// \return true on success, false if this would overflow the limit.
/// Return true on success, false if this would overflow the limit.
#[must_use]
pub fn add(&mut self, comp: impl Into<Completion>) -> bool {
if self.completions.len() >= self.limit {

6
src/env/environment.rs vendored
View File

@ -188,7 +188,7 @@ impl EnvStack {
self.inner.lock()
}
/// \return whether we are the principal stack.
/// Return whether we are the principal stack.
pub fn is_principal(&self) -> bool {
std::ptr::eq(self, Self::principal().as_ref().get_ref())
}
@ -275,7 +275,7 @@ impl EnvStack {
/// this is a user request, read-only variables can not be removed. The mode may also specify
/// the scope of the variable that should be erased.
///
/// \return the set result.
/// Return the set result.
pub fn remove(&self, key: &wstr, mode: EnvMode) -> EnvStackSetResult {
let ret = self.lock().remove(key, mode);
#[allow(clippy::collapsible_if)]
@ -329,7 +329,7 @@ impl EnvStack {
/// Synchronizes universal variable changes.
/// If `always` is set, perform synchronization even if there's no pending changes from this
/// instance (that is, look for changes from other fish instances).
/// \return a list of events for changed variables.
/// Return a list of events for changed variables.
#[allow(clippy::vec_box)]
pub fn universal_sync(&self, always: bool) -> Vec<Event> {
if UVAR_SCOPE_IS_GLOBAL.load() {

2
src/env/environment_impl.rs vendored
View File

@ -696,7 +696,7 @@ pub struct EnvStackImpl {
}
impl EnvStackImpl {
/// \return a new impl representing global variables, with a single local scope.
/// Return a new impl representing global variables, with a single local scope.
pub fn new() -> EnvMutex<EnvStackImpl> {
let globals = GLOBAL_NODE.clone();
let locals = EnvNodeRef::new(false, None);

2
src/env/var.rs vendored
View File

@ -272,7 +272,7 @@ pub const ELECTRIC_VARIABLES: &[ElectricVar] = &[
assert_sorted_by_name!(ELECTRIC_VARIABLES);
impl ElectricVar {
/// \return the ElectricVar with the given name, if any
/// Return the ElectricVar with the given name, if any
pub fn for_name(name: &wstr) -> Option<&'static ElectricVar> {
match ELECTRIC_VARIABLES.binary_search_by(|ev| ev.name.cmp(name)) {
Ok(idx) => Some(&ELECTRIC_VARIABLES[idx]),

18
src/env_universal_common.rs
View File

@ -47,7 +47,7 @@ impl CallbackData {
pub fn new(key: WString, val: Option<EnvVar>) -> Self {
Self { key, val }
}
/// \return whether this callback represents an erased variable.
/// Return whether this callback represents an erased variable.
pub fn is_erase(&self) -> bool {
self.val.is_none()
}
@ -110,7 +110,7 @@ impl EnvUniversal {
pub fn get(&self, name: &wstr) -> Option<EnvVar> {
self.vars.get(name).cloned()
}
// \return flags from the variable with the given name.
// Return flags from the variable with the given name.
pub fn get_flags(&self, name: &wstr) -> Option<EnvVarFlags> {
self.vars.get(name).map(|var| var.get_flags())
}
@ -252,7 +252,7 @@ impl EnvUniversal {
/// Populate a variable table `out_vars` from a `s` string.
/// This is exposed for testing only.
/// \return the format of the file that we read.
/// Return the format of the file that we read.
pub fn populate_variables(s: &[u8], out_vars: &mut VarTable) -> UvarFormat {
// Decide on the format.
let format = Self::format_for_contents(s);
@ -290,7 +290,7 @@ impl EnvUniversal {
}
/// Guess a file format. Exposed for testing only.
/// \return the format corresponding to file contents `s`.
/// Return the format corresponding to file contents `s`.
pub fn format_for_contents(s: &[u8]) -> UvarFormat {
// Walk over leading comments, looking for one like '# version'
let iter = LineIterator::new(s);
@ -367,7 +367,7 @@ impl EnvUniversal {
self.export_generation
}
/// \return whether we are initialized.
/// Return whether we are initialized.
fn initialized(&self) -> bool {
!self.vars_path.is_empty()
}
@ -752,7 +752,7 @@ impl EnvUniversal {
}
// Write our file contents.
// \return true on success, false on failure.
// Return true on success, false on failure.
fn save(&mut self, directory: &wstr) -> bool {
use crate::common::ScopeGuard;
assert!(self.ok_to_save, "It's not OK to save");
@ -828,7 +828,7 @@ impl EnvUniversal {
}
}
/// \return the default variable path, or an empty string on failure.
/// Return the default variable path, or an empty string on failure.
pub fn default_vars_path() -> WString {
if let Some(mut path) = default_vars_path_directory() {
path.push_str("/fish_variables");
@ -862,7 +862,7 @@ mod fish3_uvars {
pub const PATH: &[u8] = b"--path";
}
/// \return the default variable path, or an empty string on failure.
/// Return the default variable path, or an empty string on failure.
fn default_vars_path_directory() -> Option<WString> {
path_get_config()
}
@ -1007,7 +1007,7 @@ fn encode_serialized(vals: &[WString]) -> WString {
}
/// Try locking the file.
/// \return true on success, false on error.
/// Return true on success, false on error.
fn flock_uvar_file(file: &mut File) -> bool {
let start_time = timef();
while unsafe { libc::flock(file.as_raw_fd(), LOCK_EX) } == -1 {

2
src/event.rs
View File

@ -144,7 +144,7 @@ impl EventHandler {
}
}
/// \return true if a handler is "one shot": it fires at most once.
/// Return true if a handler is "one shot": it fires at most once.
fn is_one_shot(&self) -> bool {
match self.desc {
EventDescription::ProcessExit { pid } => pid != ANY_PID,

14
src/exec.rs
View File

@ -247,7 +247,7 @@ pub fn exec_job(parser: &Parser, job: &Job, block_io: IoChain) -> bool {
/// \param outputs if set, the list to insert output into.
/// \param apply_exit_status if set, update $status within the parser, otherwise do not.
///
/// \return a value appropriate for populating $status.
/// Return a value appropriate for populating $status.
pub fn exec_subshell(
cmd: &wstr,
parser: &Parser,
@ -303,7 +303,7 @@ static FORK_COUNT: AtomicUsize = AtomicUsize::new(0);
/// etc.
type LaunchResult = Result<(), ()>;
/// Given an error `err` returned from either posix_spawn or exec, \return a process exit code.
/// Given an error `err` returned from either posix_spawn or exec, Return a process exit code.
fn exit_code_from_exec_error(err: libc::c_int) -> libc::c_int {
assert!(err != 0, "Zero is success, not an error");
match err {
@ -329,7 +329,7 @@ fn exit_code_from_exec_error(err: libc::c_int) -> libc::c_int {
}
/// This is a 'looks like text' check.
/// \return true if either there is no NUL byte, or there is a line containing a lowercase letter
/// Return true if either there is no NUL byte, or there is a line containing a lowercase letter
/// before the first NUL byte.
fn is_thompson_shell_payload(p: &[u8]) -> bool {
if !p.contains(&b'\0') {
@ -744,7 +744,7 @@ fn fork_child_for_process(
Ok(())
}
/// \return an newly allocated output stream for the given fd, which is typically stdout or stderr.
/// Return an newly allocated output stream for the given fd, which is typically stdout or stderr.
/// This inspects the io_chain and decides what sort of output stream to return.
/// If `piped_output_needs_buffering` is set, and if the output is going to a pipe, then the other
/// end then synchronously writing to the pipe risks deadlock, so we must buffer it.
@ -958,7 +958,7 @@ type ProcPerformer = dyn FnOnce(
Option<&mut OutputStream>,
) -> ProcStatus;
// \return a function which may be to run the given process \p.
// Return a function which may be to run the given process \p.
// May return an empty std::function in the rare case that the to-be called fish function no longer
// exists. This is just a dumb artifact of the fact that we only capture the functions name, not its
// properties, when creating the job; thus a race could delete the function before we fetch its
@ -1366,7 +1366,7 @@ fn abort_pipeline_from(job: &Job, offset: usize) {
// Given that we are about to execute an exec() call, check if the parser is interactive and there
// are extant background jobs. If so, warn the user and do not exec().
// \return true if we should allow exec, false to disallow it.
// Return true if we should allow exec, false to disallow it.
fn allow_exec_with_background_jobs(parser: &Parser) -> bool {
// If we're not interactive, we cannot warn.
if !parser.is_interactive() {
@ -1436,7 +1436,7 @@ fn populate_subshell_output(lst: &mut Vec<WString>, buffer: &SeparatedBuffer, sp
/// If `apply_exit_status` is false, then reset $status back to its original value.
/// `is_subcmd` controls whether we apply a read limit.
/// `break_expand` is used to propagate whether the result should be "expansion breaking" in the
/// sense that subshells used during string expansion should halt that expansion. \return the value
/// sense that subshells used during string expansion should halt that expansion. Return the value
/// of $status.
fn exec_subshell_internal(
cmd: &wstr,

10
src/expand.rs
View File

@ -140,7 +140,7 @@ pub const PROCESS_EXPAND_SELF_STR: &wstr = L!("%self");
/// \param ctx The parser, variables, and cancellation checker for this operation. The parser may
/// be null. \param errors Resulting errors, or nullptr to ignore
///
/// \return An expand_result_t.
/// Return An expand_result_t.
/// wildcard_no_match and wildcard_match are normal exit conditions used only on
/// strings containing wildcards to tell if the wildcard produced any matches.
pub fn expand_string(
@ -177,7 +177,7 @@ pub fn expand_to_receiver(
/// null.
/// \param errors Resulting errors, or nullptr to ignore
///
/// \return Whether expansion succeeded.
/// Return Whether expansion succeeded.
pub fn expand_one(
s: &mut WString,
flags: ExpandFlags,
@ -208,7 +208,7 @@ pub fn expand_one(
/// that API does not distinguish between expansion resulting in an empty command (''), and
/// expansion resulting in no command (e.g. unset variable).
/// If `skip_wildcards` is true, then do not do wildcard expansion
/// \return an expand error.
/// Return an expand error.
pub fn expand_to_command_and_args(
instr: &wstr,
ctx: &OperationContext<'_>,
@ -556,7 +556,7 @@ fn parse_slice(
/// actually starts operating on last_idx-1. As such, to process a string fully, pass string.size()
/// as last_idx instead of string.size()-1.
///
/// \return the result of expansion.
/// Return the result of expansion.
fn expand_variables(
instr: WString,
out: &mut CompletionReceiver,
@ -917,7 +917,7 @@ fn expand_braces(
}
/// Expand a command substitution `input`, executing on `ctx`, and inserting the results into
/// `out_list`, or any errors into `errors`. \return an expand result.
/// `out_list`, or any errors into `errors`. Return an expand result.
pub fn expand_cmdsubst(
input: WString,
ctx: &OperationContext,

6
src/fd_monitor.rs
View File

@ -74,7 +74,7 @@ impl FdEventSignaller {
}
}
/// \return the fd to read from, for notification.
/// Return the fd to read from, for notification.
pub fn read_fd(&self) -> RawFd {
self.fd.as_raw_fd()
}
@ -140,7 +140,7 @@ impl FdEventSignaller {
/// Perform a poll to see if an event is received.
/// If `wait` is set, wait until it is readable; this does not consume the event
/// but guarantees that the next call to wait() will not block.
/// \return true if readable, false if not readable, or not interrupted by a signal.
/// Return true if readable, false if not readable, or not interrupted by a signal.
pub fn poll(&self, wait: bool /* = false */) -> bool {
let mut timeout = libc::timeval {
tv_sec: 0,
@ -165,7 +165,7 @@ impl FdEventSignaller {
res > 0
}
/// \return the fd to write to.
/// Return the fd to write to.
fn write_fd(&self) -> RawFd {
#[cfg(HAVE_EVENTFD)]
return self.fd.as_raw_fd();

6
src/fd_readable_set.rs
View File

@ -202,7 +202,7 @@ impl fd_readable_set_t {
}
/// Call select() or poll(), according to FISH_READABLE_SET_USE_POLL. Note this destructively
/// modifies the set. \return the result of select() or poll().
/// modifies the set. Return the result of select() or poll().
///
/// TODO: Change to [`Duration`](std::time::Duration) once FFI usage is done.
pub fn check_readable(&mut self, timeout_usec: u64) -> c_int {
@ -213,7 +213,7 @@ impl fd_readable_set_t {
}
/// Check if a single fd is readable, with a given timeout.
/// \return true if `fd` is our set and is readable, `false` otherwise.
/// Return true if `fd` is our set and is readable, `false` otherwise.
pub fn is_fd_readable(fd: RawFd, timeout_usec: u64) -> bool {
if fd < 0 {
return false;
@ -228,7 +228,7 @@ impl fd_readable_set_t {
}
/// Check if a single fd is readable, without blocking.
/// \return true if readable, false if not.
/// Return true if readable, false if not.
pub fn poll_fd_readable(fd: RawFd) -> bool {
return Self::is_fd_readable(fd, 0);
}

4
src/fds.rs
View File

@ -135,7 +135,7 @@ pub struct AutoClosePipes {
}
/// Construct a pair of connected pipes, set to close-on-exec.
/// \return None on fd exhaustion.
/// Return None on fd exhaustion.
pub fn make_autoclose_pipes() -> nix::Result<AutoClosePipes> {
#[allow(unused_mut, unused_assignments)]
let mut already_cloexec = false;
@ -178,7 +178,7 @@ pub fn make_autoclose_pipes() -> nix::Result<AutoClosePipes> {
/// zsh calls this movefd().
/// `input_has_cloexec` describes whether the input has CLOEXEC already set, so we can avoid
/// setting it again.
/// \return the fd, which always has CLOEXEC set; or an invalid fd on failure, in
/// Return the fd, which always has CLOEXEC set; or an invalid fd on failure, in
/// which case an error will have been printed, and the input fd closed.
fn heightenize_fd(fd: OwnedFd, input_has_cloexec: bool) -> nix::Result<OwnedFd> {
let raw_fd = fd.as_raw_fd();

10
src/function.rs
View File

@ -71,7 +71,7 @@ struct FunctionSet {
impl FunctionSet {
/// Remove a function.
/// \return true if successful, false if it doesn't exist.
/// Return true if successful, false if it doesn't exist.
fn remove(&mut self, name: &wstr) -> bool {
if self.funcs.remove(name).is_some() {
event::remove_function_handlers(name);
@ -86,7 +86,7 @@ impl FunctionSet {
self.funcs.get(name).cloned()
}
/// \return true if we should allow autoloading a given function.
/// Return true if we should allow autoloading a given function.
fn allow_autoload(&self, name: &wstr) -> bool {
// Prohibit autoloading if we have a non-autoload (explicit) function, or if the function is
// tombstoned.
@ -202,7 +202,7 @@ pub fn add(name: WString, props: Arc<FunctionProperties>) {
);
}
/// \return the properties for a function, or None. This does not trigger autoloading.
/// Return the properties for a function, or None. This does not trigger autoloading.
pub fn get_props(name: &wstr) -> Option<Arc<FunctionProperties>> {
if parser_keywords_is_reserved(name) {
None
@ -211,7 +211,7 @@ pub fn get_props(name: &wstr) -> Option<Arc<FunctionProperties>> {
}
}
/// \return the properties for a function, or None, perhaps triggering autoloading.
/// Return the properties for a function, or None, perhaps triggering autoloading.
pub fn get_props_autoload(name: &wstr, parser: &Parser) -> Option<Arc<FunctionProperties>> {
parser.assert_can_execute();
if parser_keywords_is_reserved(name) {
@ -253,7 +253,7 @@ pub fn remove(name: &wstr) {
funcset.autoload_tombstones.insert(name.to_owned());
}
// \return the body of a function (everything after the header, up to but not including the 'end').
// Return the body of a function (everything after the header, up to but not including the 'end').
fn get_function_body_source(props: &FunctionProperties) -> &wstr {
// We want to preserve comments that the AST attaches to the header (#5285).
// Take everything from the end of the header to the 'end' keyword.

6
src/highlight.rs
View File

@ -131,7 +131,7 @@ impl HighlightColorResolver {
pub fn new() -> Self {
Default::default()
}
/// \return an RGB color for a given highlight spec.
/// Return an RGB color for a given highlight spec.
pub fn resolve_spec(
&mut self,
highlight: &HighlightSpec,
@ -977,7 +977,7 @@ impl<'s> Highlighter<'s> {
std::mem::take(&mut self.color_array)
}
/// \return a substring of our buffer.
/// Return a substring of our buffer.
pub fn get_source(&self, r: SourceRange) -> &'s wstr {
assert!(r.end() >= r.start(), "Overflow");
assert!(r.end() <= self.buff.len(), "Out of range");
@ -1397,7 +1397,7 @@ impl<'s> Highlighter<'s> {
}
}
/// \return whether a string contains a command substitution.
/// Return whether a string contains a command substitution.
fn has_cmdsub(src: &wstr) -> bool {
let mut cursor = 0;
match parse_util_locate_cmdsubst_range(src, &mut cursor, true, None, None) {

12
src/input.rs
View File

@ -87,7 +87,7 @@ impl InputMapping {
}
}
/// \return true if this is a generic mapping, i.e. acts as a fallback.
/// Return true if this is a generic mapping, i.e. acts as a fallback.
fn is_generic(&self) -> bool {
self.seq.is_empty()
}
@ -620,7 +620,7 @@ impl EventQueuePeeker<'_> {
}
}
/// \return the next event.
/// Return the next event.
fn next(&mut self) -> CharEvent {
assert!(self.subidx == 0);
assert!(
@ -773,7 +773,7 @@ impl Drop for EventQueuePeeker<'_> {
}
}
/// \return true if a given `peeker` matches a given sequence of char events given by `str`.
/// Return true if a given `peeker` matches a given sequence of char events given by `str`.
fn try_peek_sequence(peeker: &mut EventQueuePeeker, style: &KeyNameStyle, seq: &[Key]) -> bool {
assert!(
!seq.is_empty(),
@ -799,9 +799,9 @@ fn try_peek_sequence(peeker: &mut EventQueuePeeker, style: &KeyNameStyle, seq: &
true
}
/// \return the first mapping that matches, walking first over the user's mapping list, then the
/// Return the first mapping that matches, walking first over the user's mapping list, then the
/// preset list.
/// \return none if nothing matches, or if we may have matched a longer sequence but it was
/// Return none if nothing matches, or if we may have matched a longer sequence but it was
/// interrupted by a readline event.
impl Inputter {
fn find_mapping(vars: &dyn Environment, peeker: &mut EventQueuePeeker) -> Option<InputMapping> {
@ -1064,7 +1064,7 @@ impl InputMappingSet {
false
}
/// \return a snapshot of the list of input mappings.
/// Return a snapshot of the list of input mappings.
fn all_mappings(&self) -> Arc<Box<[InputMapping]>> {
// Populate the cache if needed.
let mut cache = self.all_mappings_cache.borrow_mut();

6
src/input_common.rs
View File

@ -549,7 +549,7 @@ fn parse_mask(mask: u32) -> Modifiers {
/// A trait which knows how to produce a stream of input events.
/// Note this is conceptually a "base class" with override points.
pub trait InputEventQueuer {
/// \return the next event in the queue, or none if the queue is empty.
/// Return the next event in the queue, or none if the queue is empty.
fn try_pop(&mut self) -> Option<CharEvent> {
self.get_queue_mut().pop_front()
}
@ -1040,7 +1040,7 @@ pub trait InputEventQueuer {
/// Like readch(), except it will wait at most wait_time_ms milliseconds for a
/// character to be available for reading.
/// \return None on timeout, the event on success.
/// Return None on timeout, the event on success.
fn readch_timed(&mut self, wait_time_ms: usize) -> Option<CharEvent> {
if let Some(evt) = self.try_pop() {
return Some(evt);
@ -1189,7 +1189,7 @@ pub trait InputEventQueuer {
/// The default does nothing.
fn uvar_change_notified(&mut self) {}
/// \return if we have any lookahead.
/// Return if we have any lookahead.
fn has_lookahead(&self) -> bool {
!self.get_queue().is_empty()
}

30
src/io.rs
View File

@ -82,17 +82,17 @@ impl SeparatedBuffer {
}
}
/// \return the buffer limit size, or 0 for no limit.
/// Return the buffer limit size, or 0 for no limit.
pub fn limit(&self) -> usize {
self.buffer_limit
}
/// \return the contents size.
/// Return the contents size.
pub fn len(&self) -> usize {
self.contents_size
}
/// \return whether the output has been discarded.
/// Return whether the output has been discarded.
pub fn discarded(&self) -> bool {
self.discard
}
@ -110,7 +110,7 @@ impl SeparatedBuffer {
result
}
/// \return the list of elements.
/// Return the list of elements.
pub fn elements(&self) -> &[BufferElement] {
&self.elements
}
@ -140,12 +140,12 @@ impl SeparatedBuffer {
self.discard = false;
}
/// \return true if our last element has an inferred separation type.
/// Return true if our last element has an inferred separation type.
fn last_inferred(&self) -> bool {
!self.elements.is_empty() && !self.elements.last().unwrap().is_explicitly_separated()
}
/// Mark that we are about to add the given size `delta` to the buffer. \return true if we
/// Mark that we are about to add the given size `delta` to the buffer. Return true if we
/// succeed, false if we exceed buffer_limit.
fn try_add_size(&mut self, delta: usize) -> bool {
if self.discard {
@ -346,12 +346,12 @@ pub struct IoBufferfill {
}
impl IoBufferfill {
/// Create an io_bufferfill_t which, when written from, fills a buffer with the contents.
/// \returns an error on failure, e.g. too many open fds.
/// Returns an error on failure, e.g. too many open fds.
pub fn create() -> io::Result<Arc<IoBufferfill>> {
Self::create_opts(0, STDOUT_FILENO)
}
/// Create an io_bufferfill_t which, when written from, fills a buffer with the contents.
/// \returns an error on failure, e.g. too many open fds.
/// Returns an error on failure, e.g. too many open fds.
///
/// \param target the fd which this will be dup2'd to - typically stdout.
pub fn create_opts(buffer_limit: usize, target: RawFd) -> io::Result<Arc<IoBufferfill>> {
@ -389,7 +389,7 @@ impl IoBufferfill {
}
/// Reset the receiver (possibly closing the write end of the pipe), and complete the fillthread
/// of the buffer. \return the buffer.
/// of the buffer. Return the buffer.
pub fn finish(filler: Arc<IoBufferfill>) -> SeparatedBuffer {
// The io filler is passed in. This typically holds the only instance of the write side of the
// pipe used by the buffer's fillthread (except for that side held by other processes). Get the
@ -462,13 +462,13 @@ impl IoBuffer {
self.buffer.lock().unwrap().append(data, typ)
}
/// \return true if output was discarded due to exceeding the read limit.
/// Return true if output was discarded due to exceeding the read limit.
pub fn discarded(&self) -> bool {
self.buffer.lock().unwrap().discarded()
}
/// Read some, filling the buffer. The buffer is passed in to enforce that the append lock is
/// held. \return positive on success, 0 if closed, -1 on error (in which case errno will be
/// held. Return positive on success, 0 if closed, -1 on error (in which case errno will be
/// set).
pub fn read_once(fd: RawFd, buffer: &mut MutexGuard<'_, SeparatedBuffer>) -> isize {
assert!(fd >= 0, "Invalid fd");
@ -636,14 +636,14 @@ impl IoChain {
true
}
/// \return the last io redirection in the chain for the specified file descriptor, or nullptr
/// Return the last io redirection in the chain for the specified file descriptor, or nullptr
/// if none.
pub fn io_for_fd(&self, fd: RawFd) -> Option<IoDataRef> {
self.0.iter().rev().find(|data| data.fd() == fd).cloned()
}
/// Attempt to resolve a list of redirection specs to IOs, appending to 'this'.
/// \return true on success, false on error, in which case an error will have been printed.
/// Return true on success, false on error, in which case an error will have been printed.
#[allow(clippy::collapsible_else_if)]
pub fn append_from_specs(&mut self, specs: &RedirectionSpecList, pwd: &wstr) -> bool {
let mut have_error = false;
@ -771,7 +771,7 @@ pub enum OutputStream {
}
impl OutputStream {
/// \return any internally buffered contents.
/// Return any internally buffered contents.
/// This is only implemented for a string_output_stream; others flush data to their underlying
/// receiver (fd, or separated buffer) immediately and so will return an empty string here.
pub fn contents(&self) -> &wstr {
@ -930,7 +930,7 @@ impl StringOutputStream {
self.contents.push_utfstr(s);
true
}
/// \return the wcstring containing the output.
/// Return the wcstring containing the output.
fn contents(&self) -> &wstr {
&self.contents
}

2
src/locale.rs
View File

@ -8,7 +8,7 @@ pub(crate) static LOCALE_LOCK: Mutex<()> = Mutex::new(());
/// It's CHAR_MAX.
const CHAR_MAX: libc::c_char = libc::c_char::max_value();
/// \return the first character of a C string, or None if null, empty, has a length more than 1, or negative.
/// Return the first character of a C string, or None if null, empty, has a length more than 1, or negative.
unsafe fn first_char(s: *const libc::c_char) -> Option<char> {
#[allow(unused_comparisons, clippy::absurd_extreme_comparisons)]
if !s.is_null() && *s > 0 && *s <= 127 && *s.offset(1) == 0 {

8
src/operation_context.rs
View File

@ -58,12 +58,12 @@ impl<'a> OperationContext<'a> {
}
}
// \return an "empty" context which contains no variables, no parser, and never cancels.
// Return an "empty" context which contains no variables, no parser, and never cancels.
pub fn empty() -> OperationContext<'static> {
OperationContext::background(&**nullenv, EXPANSION_LIMIT_DEFAULT)
}
// \return an operation context that contains only global variables, no parser, and never
// Return an operation context that contains only global variables, no parser, and never
// cancels.
pub fn globals() -> OperationContext<'static> {
OperationContext::background(&**EnvStack::globals(), EXPANSION_LIMIT_DEFAULT)
@ -136,13 +136,13 @@ impl<'a> OperationContext<'a> {
Vars::TestOnly(parser, _) => parser,
}
}
// Invoke the cancel checker. \return if we should cancel.
// Invoke the cancel checker. Return if we should cancel.
pub fn check_cancel(&self) -> bool {
(self.cancel_checker)()
}
}
/// \return an operation context for a background operation..
/// Return an operation context for a background operation..
/// Crucially the operation context itself does not contain a parser.
/// It is the caller's responsibility to ensure the environment lives as long as the result.
pub fn get_bg_context(env: &EnvDyn, generation_count: u32) -> OperationContext {

2
src/output.rs
View File

@ -380,7 +380,7 @@ impl Outputter {
self.maybe_flush();
}
/// \return the "output" contents.
/// Return the "output" contents.
pub fn contents(&self) -> &[u8] {
&self.contents
}

2
src/pager.rs
View File

@ -910,7 +910,7 @@ impl Pager {
rendering
}
// \return true if the given rendering needs to be updated.
// Return true if the given rendering needs to be updated.
pub fn rendering_needs_update(&self, rendering: &PageRendering) -> bool {
if self.have_unrendered_completions {
return true;

2
src/parse_constants.rs
View File

@ -164,7 +164,7 @@ impl SourceRange {
}
}
// \return true if a location is in this range, including one-past-the-end.
// Return true if a location is in this range, including one-past-the-end.
pub fn contains_inclusive(&self, loc: usize) -> bool {
self.start() <= loc && loc - self.start() <= self.length()
}

4
src/parse_execution.rs
View File

@ -258,7 +258,7 @@ impl<'a> ParseExecutionContext {
}
// Check to see if we should end execution.
// \return the eval result to end with, or none() to continue on.
// Return the eval result to end with, or none() to continue on.
// This will never return end_execution_reason_t::ok.
fn check_end_execution(&self, ctx: &OperationContext<'_>) -> Option<EndExecutionReason> {
// If one of our jobs ended with SIGINT, we stop execution.
@ -1932,7 +1932,7 @@ impl<'a> ParseExecutionContext {
j.mut_flags().is_group_root = true;
}
// \return whether we should apply job control to our processes.
// Return whether we should apply job control to our processes.
fn use_job_control(&self, ctx: &OperationContext<'_>) -> bool {
if ctx.parser().is_command_substitution() {
return false;

4
src/parse_tree.rs
View File

@ -60,12 +60,12 @@ impl ParseToken {
pub fn source_length(&self) -> usize {
self.source_length.try_into().unwrap()
}
/// \return the source range.
/// Return the source range.
/// Note the start may be invalid.
pub fn range(&self) -> SourceRange {
SourceRange::new(self.source_start(), self.source_length())
}
/// \return whether we are a string with the dash prefix set.
/// Return whether we are a string with the dash prefix set.
pub fn is_dash_prefix_string(&self) -> bool {
self.typ == ParseTokenType::string && self.has_dash_prefix
}

8
src/parse_util.rs
View File

@ -31,7 +31,7 @@ use std::ops::Range;
use std::{iter, ops};
/// Handles slices: the square brackets in an expression like $foo[5..4]
/// \return the length of the slice starting at `in`, or 0 if there is no slice, or None on error.
/// Return the length of the slice starting at `in`, or 0 if there is no slice, or None on error.
/// This never accepts incomplete slices.
pub fn parse_util_slice_length(input: &wstr) -> Option<usize> {
const openc: char = '[';
@ -124,7 +124,7 @@ pub enum MaybeParentheses {
/// \param accept_incomplete whether to permit missing closing parenthesis
/// \param inout_is_quoted whether the cursor is in a double-quoted context.
/// \param out_has_dollar whether the command substitution has the optional leading $.
/// \return -1 on syntax error, 0 if no subshells exist and 1 on success
/// Return -1 on syntax error, 0 if no subshells exist and 1 on success
#[allow(clippy::too_many_arguments)]
pub fn parse_util_locate_cmdsubst_range(
s: &wstr,
@ -649,7 +649,7 @@ fn parser_is_pipe_forbidden(word: &wstr) -> bool {
.contains(&word)
}
// \return a pointer to the first argument node of an argument_or_redirection_list_t, or nullptr if
// Return a pointer to the first argument node of an argument_or_redirection_list_t, or nullptr if
// there are no arguments.
fn get_first_arg(list: &ast::ArgumentOrRedirectionList) -> Option<&ast::Argument> {
for v in list.iter() {
@ -871,7 +871,7 @@ impl<'a> IndentVisitor<'a> {
line_continuations: vec![],
}
}
/// \return whether a maybe_newlines node contains at least one newline.
/// Return whether a maybe_newlines node contains at least one newline.
fn has_newline(&self, nls: &ast::MaybeNewlines) -> bool {
nls.source(self.src).chars().any(|c| c == '\n')
}

22
src/parser.rs
View File

@ -127,7 +127,7 @@ impl Block {
self.block_type
}
/// \return if we are a function call (with or without shadowing).
/// Return if we are a function call (with or without shadowing).
pub fn is_function_call(&self) -> bool {
[BlockType::function_call, BlockType::function_call_no_shadow].contains(&self.typ())
}
@ -202,7 +202,7 @@ impl ProfileItem {
pub fn new() -> Self {
Default::default()
}
/// \return the current time as a microsecond timestamp since the epoch.
/// Return the current time as a microsecond timestamp since the epoch.
pub fn now() -> Microseconds {
get_time()
}
@ -374,7 +374,7 @@ impl Parser {
self.jobs_mut().insert(0, job);
}
/// \return whether we are currently evaluating a function.
/// Return whether we are currently evaluating a function.
pub fn is_function(&self) -> bool {
let blocks = self.blocks();
for b in blocks.iter().rev() {
@ -388,7 +388,7 @@ impl Parser {
false
}
/// \return whether we are currently evaluating a command substitution.
/// Return whether we are currently evaluating a command substitution.
pub fn is_command_substitution(&self) -> bool {
let blocks = self.blocks();
for b in blocks.iter().rev() {
@ -425,7 +425,7 @@ impl Parser {
/// \param job_group if set, the job group to give to spawned jobs.
/// \param block_type The type of block to push on the block stack, which must be either 'top'
/// or 'subst'.
/// \return the result of evaluation.
/// Return the result of evaluation.
pub fn eval_with(
&self,
cmd: &wstr,
@ -693,7 +693,7 @@ impl Parser {
.and_then(|ctx| ctx.get_current_line_number())
}
/// \return whether we are currently evaluating a "block" such as an if statement.
/// Return whether we are currently evaluating a "block" such as an if statement.
/// This supports 'status is-block'.
pub fn is_block(&self) -> bool {
// Note historically this has descended into 'source', unlike 'is_function'.
@ -706,7 +706,7 @@ impl Parser {
false
}
/// \return whether we have a breakpoint block.
/// Return whether we have a breakpoint block.
pub fn is_breakpoint(&self) -> bool {
let blocks = self.blocks();
for b in blocks.iter().rev() {
@ -792,7 +792,7 @@ impl Parser {
}
/// Cover of vars().set(), which also fires any returned event handlers.
/// \return a value like ENV_OK.
/// Return a value like ENV_OK.
pub fn set_var_and_fire(
&self,
key: &wstr,
@ -1043,7 +1043,7 @@ impl Parser {
trace
}
/// \return whether the number of functions in the stack exceeds our stack depth limit.
/// Return whether the number of functions in the stack exceeds our stack depth limit.
pub fn function_stack_is_overflowing(&self) -> bool {
// We are interested in whether the count of functions on the stack exceeds
// FISH_MAX_STACK_DEPTH. We don't separately track the number of functions, but we can have a
@ -1066,12 +1066,12 @@ impl Parser {
self.syncs_uvars.store(flag);
}
/// \return a shared pointer reference to this parser.
/// Return a shared pointer reference to this parser.
pub fn shared(&self) -> ParserRef {
self.this.upgrade().unwrap()
}
/// \return the operation context for this parser.
/// Return the operation context for this parser.
pub fn context(&self) -> OperationContext<'static> {
OperationContext::foreground(
self.shared(),

20
src/path.rs
View File

@ -21,7 +21,7 @@ use std::os::unix::prelude::*;
/// doesn't exist, they are first created.
///
/// \param path The directory as an out param
/// \return whether the directory was returned successfully
/// Return whether the directory was returned successfully
pub fn path_get_config() -> Option<WString> {
let dir = get_config_directory();
if dir.success() {
@ -37,7 +37,7 @@ pub fn path_get_config() -> Option<WString> {
/// Volatile files presumed to be local to the machine, such as the fish_history will be stored in this directory.
///
/// \param path The directory as an out param
/// \return whether the directory was returned successfully
/// Return whether the directory was returned successfully
pub fn path_get_data() -> Option<WString> {
let dir = get_data_directory();
if dir.success() {
@ -54,7 +54,7 @@ pub fn path_get_data() -> Option<WString> {
/// generated_completions, will be stored in this directory.
///
/// \param path The directory as an out param
/// \return whether the directory was returned successfully
/// Return whether the directory was returned successfully
pub fn path_get_cache() -> Option<WString> {
let dir = get_cache_directory();
if dir.success() {
@ -74,7 +74,7 @@ pub enum DirRemoteness {
remote,
}
/// \return the remoteness of the fish data directory.
/// Return the remoteness of the fish data directory.
/// This will be remote for filesystems like NFS, SMB, etc.
pub fn path_get_data_remoteness() -> DirRemoteness {
get_data_directory().remoteness
@ -187,7 +187,7 @@ fn maybe_issue_path_warning(
}
/// Finds the path of an executable named `cmd`, by looking in $PATH taken from `vars`.
/// \returns the path if found, none if not.
/// Returns the path if found, none if not.
pub fn path_get_path(cmd: &wstr, vars: &dyn Environment) -> Option<WString> {
let result = path_try_get_path(cmd, vars);
if result.err.is_some() {
@ -276,7 +276,7 @@ pub fn path_get_paths(cmd: &wstr, vars: &dyn Environment) -> Vec<WString> {
fn path_get_path_core<S: AsRef<wstr>>(cmd: &wstr, pathsv: &[S]) -> GetPathResult {
let noent_res = GetPathResult::new(Some(Errno(ENOENT)), WString::new());
// Test if the given path can be executed.
// \return 0 on success, an errno value on failure.
// Return 0 on success, an errno value on failure.
let test_path = |path: &wstr| -> Result<(), Errno> {
let narrow = wcs2zstring(path);
if unsafe { libc::access(narrow.as_ptr(), X_OK) } != 0 {
@ -346,7 +346,7 @@ fn path_get_path_core<S: AsRef<wstr>>(cmd: &wstr, pathsv: &[S]) -> GetPathResult
/// \param dir The name of the directory.
/// \param wd The working directory. The working directory must end with a slash.
/// \param vars The environment variables to use (for the CDPATH variable)
/// \return the command, or none() if it could not be found.
/// Return the command, or none() if it could not be found.
pub fn path_get_cdpath(dir: &wstr, wd: &wstr, vars: &dyn Environment) -> Option<WString> {
let mut err = ENOENT;
if dir.is_empty() {
@ -592,7 +592,7 @@ impl BaseDirectory {
}
/// Attempt to get a base directory, creating it if necessary. If a variable named `xdg_var` is
/// set, use that directory; otherwise use the path `non_xdg_homepath` rooted in $HOME. \return the
/// set, use that directory; otherwise use the path `non_xdg_homepath` rooted in $HOME. Return the
/// result; see the base_directory_t fields.
#[cfg_attr(test, allow(unused_variables), allow(unreachable_code))]
fn make_base_directory(xdg_var: &wstr, non_xdg_homepath: &wstr) -> BaseDirectory {
@ -665,7 +665,7 @@ fn make_base_directory(xdg_var: &wstr, non_xdg_homepath: &wstr) -> BaseDirectory
/// Make sure the specified directory exists. If needed, try to create it and any currently not
/// existing parent directories, like mkdir -p,.
///
/// \return 0 if, at the time of function return the directory exists, -1 otherwise.
/// Return 0 if, at the time of function return the directory exists, -1 otherwise.
fn create_directory(d: &wstr) -> bool {
let md = loop {
match wstat(d) {
@ -683,7 +683,7 @@ fn create_directory(d: &wstr) -> bool {
}
}
/// \return whether the given path is on a remote filesystem.
/// Return whether the given path is on a remote filesystem.
fn path_remoteness(path: &wstr) -> DirRemoteness {
let narrow = wcs2zstring(path);
#[cfg(target_os = "linux")]

62
src/proc.rs
View File

@ -82,7 +82,7 @@ impl TryFrom<&wstr> for JobControl {
/// A number of clock ticks.
pub type ClockTicks = u64;
/// \return clock ticks in seconds, or 0 on failure.
/// Return clock ticks in seconds, or 0 on failure.
/// This uses sysconf(_SC_CLK_TCK) to convert to seconds.
pub fn clock_ticks_to_seconds(ticks: ClockTicks) -> f64 {
let clock_ticks_per_sec = unsafe { libc::sysconf(_SC_CLK_TCK) };
@ -200,44 +200,44 @@ impl ProcStatus {
ProcStatus::new(0, empty)
}
/// \return if we are stopped (as in SIGSTOP).
/// Return if we are stopped (as in SIGSTOP).
pub fn stopped(&self) -> bool {
WIFSTOPPED(self.status())
}
/// \return if we are continued (as in SIGCONT).
/// Return if we are continued (as in SIGCONT).
pub fn continued(&self) -> bool {
WIFCONTINUED(self.status())
}
/// \return if we exited normally (not a signal).
/// Return if we exited normally (not a signal).
pub fn normal_exited(&self) -> bool {
WIFEXITED(self.status())
}
/// \return if we exited because of a signal.
/// Return if we exited because of a signal.
pub fn signal_exited(&self) -> bool {
WIFSIGNALED(self.status())
}
/// \return the signal code, given that we signal exited.
/// Return the signal code, given that we signal exited.
pub fn signal_code(&self) -> libc::c_int {
assert!(self.signal_exited(), "Process is not signal exited");
WTERMSIG(self.status())
}
/// \return the exit code, given that we normal exited.
/// Return the exit code, given that we normal exited.
pub fn exit_code(&self) -> libc::c_int {
assert!(self.normal_exited(), "Process is not normal exited");
WEXITSTATUS(self.status())
}
/// \return if this status represents success.
/// Return if this status represents success.
pub fn is_success(&self) -> bool {
self.normal_exited() && self.exit_code() == EXIT_SUCCESS
}
/// \return the value appropriate to populate $status.
/// Return the value appropriate to populate $status.
pub fn status_value(&self) -> i32 {
if self.signal_exited() {
128 + self.signal_code()
@ -273,7 +273,7 @@ impl InternalProc {
}
}
/// \return if this process has exited.
/// Return if this process has exited.
pub fn exited(&self) -> bool {
self.exited.load(Ordering::Acquire)
}
@ -683,7 +683,7 @@ impl Process {
}
}
/// \return whether this process type is internal (block, function, or builtin).
/// Return whether this process type is internal (block, function, or builtin).
pub fn is_internal(&self) -> bool {
match self.typ {
ProcessType::builtin | ProcessType::function | ProcessType::block_node => true,
@ -691,7 +691,7 @@ impl Process {
}
}
/// \return the wait handle for the process, if it exists.
/// Return the wait handle for the process, if it exists.
pub fn get_wait_handle(&self) -> Option<WaitHandleRef> {
self.wait_handle.borrow().clone()
}
@ -821,7 +821,7 @@ impl Job {
&mut self.processes
}
/// \return whether it is OK to reap a given process. Sometimes we want to defer reaping a
/// Return whether it is OK to reap a given process. Sometimes we want to defer reaping a
/// process if it is the group leader and the job is not yet constructed, because then we might
/// also reap the process group and then we cannot add new processes to the group.
pub fn can_reap(&self, p: &ProcessPtr) -> bool {
@ -848,13 +848,13 @@ impl Job {
result.to_owned() + L!("...")
}
/// \return our pgid, or none if we don't have one, or are internal to fish
/// Return our pgid, or none if we don't have one, or are internal to fish
/// This never returns fish's own pgroup.
pub fn get_pgid(&self) -> Option<libc::pid_t> {
self.group().get_pgid()
}
/// \return the pid of the last external process in the job.
/// Return the pid of the last external process in the job.
/// This may be none if the job consists of just internal fish functions or builtins.
/// This will never be fish's own pid.
pub fn get_last_pid(&self) -> Option<libc::pid_t> {
@ -881,12 +881,12 @@ impl Job {
self.job_flags.borrow_mut()
}
/// \return if we want job control.
/// Return if we want job control.
pub fn wants_job_control(&self) -> bool {
self.group().wants_job_control()
}
/// \return whether this job is initially going to run in the background, because & was
/// Return whether this job is initially going to run in the background, because & was
/// specified.
pub fn is_initially_background(&self) -> bool {
self.properties.initial_background
@ -898,14 +898,14 @@ impl Job {
self.mut_flags().constructed = true;
}
/// \return whether we have internal or external procs, respectively.
/// Return whether we have internal or external procs, respectively.
/// Internal procs are builtins, blocks, and functions.
/// External procs include exec and external.
pub fn has_external_proc(&self) -> bool {
self.processes().iter().any(|p| !p.is_internal())
}
/// \return whether this job, when run, will want a job ID.
/// Return whether this job, when run, will want a job ID.
/// Jobs that are only a single internal block do not get a job ID.
pub fn wants_job_id(&self) -> bool {
self.processes().len() > 1
@ -949,12 +949,12 @@ impl Job {
self.properties.from_event_handler
}
/// \return whether this job's group is in the foreground.
/// Return whether this job's group is in the foreground.
pub fn is_foreground(&self) -> bool {
self.group().is_foreground()
}
/// \return whether we should post job_exit events.
/// Return whether we should post job_exit events.
pub fn posts_job_exit_events(&self) -> bool {
// Only report root job exits.
// For example in `ls | begin ; cat ; end` we don't need to report the cat sub-job.
@ -1004,7 +1004,7 @@ impl Job {
}
/// Prepare to resume a stopped job by sending SIGCONT and clearing the stopped flag.
/// \return true on success, false if we failed to send the signal.
/// Return true on success, false if we failed to send the signal.
pub fn resume(&self) -> bool {
self.mut_flags().notified_of_stop = false;
if !self.signal(SIGCONT) {
@ -1024,7 +1024,7 @@ impl Job {
}
/// Send the specified signal to all processes in this job.
/// \return true on success, false on failure.
/// Return true on success, false on failure.
pub fn signal(&self, signal: i32) -> bool {
if let Some(pgid) = self.group().get_pgid() {
if unsafe { libc::killpg(pgid, signal) } == -1 {
@ -1049,7 +1049,7 @@ impl Job {
true
}
/// \returns the statuses for this job.
/// Returns the statuses for this job.
pub fn get_statuses(&self) -> Option<Statuses> {
let mut st = Statuses::default();
let mut has_status = false;
@ -1146,7 +1146,7 @@ static JOB_CONTROL_MODE: AtomicU8 = AtomicU8::new(JobControl::interactive as u8)
/// Notify the user about stopped or terminated jobs, and delete completed jobs from the job list.
/// If `interactive` is set, allow removing interactive jobs; otherwise skip them.
/// \return whether text was printed to stdout.
/// Return whether text was printed to stdout.
pub fn job_reap(parser: &Parser, allow_interactive: bool) -> bool {
parser.assert_can_execute();
@ -1159,7 +1159,7 @@ pub fn job_reap(parser: &Parser, allow_interactive: bool) -> bool {
process_clean_after_marking(parser, allow_interactive)
}
/// \return the list of background jobs which we should warn the user about, if the user attempts to
/// Return the list of background jobs which we should warn the user about, if the user attempts to
/// exit. An empty result (common) means no such jobs.
pub fn jobs_requiring_warning_on_exit(parser: &Parser) -> JobList {
let mut result = vec![];
@ -1505,7 +1505,7 @@ fn generate_job_exit_events(j: &Job, out_evts: &mut Vec<Event>) {
out_evts.push(Event::caller_exit(j.internal_job_id, j.job_id()));
}
/// \return whether to emit a fish_job_summary call for a process.
/// Return whether to emit a fish_job_summary call for a process.
fn proc_wants_summary(j: &Job, p: &Process) -> bool {
// Are we completed with a pid?
if !p.is_completed() || !p.has_pid() {
@ -1527,7 +1527,7 @@ fn proc_wants_summary(j: &Job, p: &Process) -> bool {
true
}
/// \return whether to emit a fish_job_summary call for a job as a whole. We may also emit this for
/// Return whether to emit a fish_job_summary call for a job as a whole. We may also emit this for
/// its individual processes.
fn job_wants_summary(j: &Job) -> bool {
// Do we just skip notifications?
@ -1550,7 +1550,7 @@ fn job_wants_summary(j: &Job) -> bool {
true
}
/// \return whether we want to emit a fish_job_summary call for a job or any of its processes.
/// Return whether we want to emit a fish_job_summary call for a job or any of its processes.
fn job_or_proc_wants_summary(j: &Job) -> bool {
job_wants_summary(j) || j.processes().iter().any(|p| proc_wants_summary(j, p))
}
@ -1565,7 +1565,7 @@ fn call_job_summary(parser: &Parser, cmd: &wstr) {
parser.pop_block(b);
}
// \return a command which invokes fish_job_summary.
// Return a command which invokes fish_job_summary.
// The process pointer may be null, in which case it represents the entire job.
// Note this implements the arguments which fish_job_summary expects.
fn summary_command(j: &Job, p: Option<&Process>) -> WString {
@ -1668,7 +1668,7 @@ fn save_wait_handle_for_completed_job(job: &Job, store: &mut WaitHandleStore) {
}
/// Remove completed jobs from the job list, printing status messages as appropriate.
/// \return whether something was printed.
/// Return whether something was printed.
fn process_clean_after_marking(parser: &Parser, allow_interactive: bool) -> bool {
parser.assert_can_execute();

24
src/reader.rs
View File

@ -221,7 +221,7 @@ pub fn current_data() -> Option<&'static mut ReaderData> {
pub use current_data as reader_current_data;
/// Add a new reader to the reader stack.
/// \return a shared pointer to it.
/// Return a shared pointer to it.
fn reader_push_ret(
parser: &Parser,
history_name: &wstr,
@ -1342,7 +1342,7 @@ pub fn combine_command_and_autosuggestion(cmdline: &wstr, autosuggestion: &wstr)
}
impl ReaderData {
/// \return true if the command line has changed and repainting is needed. If `colors` is not
/// Return true if the command line has changed and repainting is needed. If `colors` is not
/// null, then also return true if the colors have changed.
fn is_repaint_needed(&self, mcolors: Option<&[HighlightSpec]>) -> bool {
// Note: this function is responsible for detecting all of the ways that the command line may
@ -1785,7 +1785,7 @@ impl ReaderData {
impl ReaderData {
/// Read a command to execute, respecting input bindings.
/// \return the command, or none if we were asked to cancel (e.g. SIGHUP).
/// Return the command, or none if we were asked to cancel (e.g. SIGHUP).
fn readline(&mut self, nchars: Option<NonZeroUsize>) -> Option<WString> {
self.rls = Some(ReadlineLoopState::new());
@ -1950,7 +1950,7 @@ impl ReaderData {
}
/// Read normal characters, inserting them into the command line.
/// \return the next unhandled event.
/// Return the next unhandled event.
fn read_normal_chars(&mut self) -> Option<CharEvent> {
let mut event_needing_handling = None;
let limit = std::cmp::min(
@ -3185,7 +3185,7 @@ fn text_ends_in_comment(text: &wstr) -> bool {
impl ReaderData {
// Handle readline_cmd_t::execute. This may mean inserting a newline if the command is
// unfinished. It may also set 'finished' and 'cmd' inside the rls.
// \return true on success, false if we got an error, in which case the caller should fire the
// Return true on success, false if we got an error, in which case the caller should fire the
// error event.
fn handle_execute(&mut self) -> bool {
// Evaluate. If the current command is unfinished, or if the charater is escaped
@ -3264,7 +3264,7 @@ impl ReaderData {
// Expand abbreviations before execution.
// Replace the command line with any abbreviations as needed.
// \return the test result, which may be incomplete to insert a newline, or an error.
// Return the test result, which may be incomplete to insert a newline, or an error.
fn expand_for_execute(&mut self) -> Result<(), ParserTestErrorBits> {
// Expand abbreviations at the cursor.
// The first expansion is "user visible" and enters into history.
@ -3698,7 +3698,7 @@ fn reader_interactive_destroy() {
.set_color(RgbColor::RESET, RgbColor::RESET);
}
/// \return whether fish is currently unwinding the stack in preparation to exit.
/// Return whether fish is currently unwinding the stack in preparation to exit.
pub fn fish_is_unwinding_for_exit() -> bool {
let exit_state = EXIT_STATE.load(Ordering::Relaxed);
let exit_state: ExitState = unsafe { std::mem::transmute(exit_state) };
@ -3920,7 +3920,7 @@ impl Autosuggestion {
self.search_string.clear();
}
// \return whether we have empty text.
// Return whether we have empty text.
fn is_empty(&self) -> bool {
self.text.is_empty()
}
@ -4438,7 +4438,7 @@ impl ReaderData {
}
/// Expand an abbreviation replacer, which may mean running its function.
/// \return the replacement, or none to skip it. This may run fish script!
/// Return the replacement, or none to skip it. This may run fish script!
fn expand_replacer(
range: SourceRange,
token: &wstr,
@ -4570,7 +4570,7 @@ fn extract_tokens(s: &wstr) -> Vec<PositionedToken> {
/// Expand at most one abbreviation at the given cursor position, updating the position if the
/// abbreviation wants to move the cursor. Use the parser to run any abbreviations which want
/// function calls. \return none if no abbreviations were expanded, otherwise the resulting
/// function calls. Return none if no abbreviations were expanded, otherwise the resulting
/// replacement.
pub fn reader_expand_abbreviation_at_cursor(
cmdline: &wstr,
@ -4975,7 +4975,7 @@ impl ReaderData {
}
/// Check if we should exit the reader loop.
/// \return true if we should exit.
/// Return true if we should exit.
pub fn check_exit_loop_maybe_warning(data: Option<&mut ReaderData>) -> bool {
// sighup always forces exit.
if reader_received_sighup() {
@ -5163,7 +5163,7 @@ pub(crate) fn get_quote(cmd_str: &wstr, len: usize) -> Option<char> {
/// \param append_only Whether we can only append to the command line, or also modify previous
/// characters. This is used to determine whether we go inside a trailing quote.
///
/// \return The completed string
/// Return The completed string
pub fn completion_apply_to_command_line(
val_str: &wstr,
flags: CompleteFlags,

12
src/reader_history_search.rs
View File

@ -101,17 +101,17 @@ impl ReaderHistorySearch {
self.match_index = 0;
}
/// \return the current search result.
/// Return the current search result.
pub fn current_result(&self) -> &wstr {
&self.matches[self.match_index].text
}
/// \return the string we are searching for.
/// Return the string we are searching for.
pub fn search_string(&self) -> &wstr {
self.search().original_term()
}
/// \return the range of the original search string in the new command line.
/// Return the range of the original search string in the new command line.
pub fn search_range_if_active(&self) -> Option<SourceRange> {
if !self.active() || self.is_at_end() {
return None;
@ -122,13 +122,13 @@ impl ReaderHistorySearch {
))
}
/// \return whether we are at the end (most recent) of our search.
/// Return whether we are at the end (most recent) of our search.
pub fn is_at_end(&self) -> bool {
self.match_index == 0
}
// Add an item to skip.
// \return true if it was added, false if already present.
// Return true if it was added, false if already present.
pub fn add_skip(&mut self, s: WString) -> bool {
self.skips.insert(s)
}
@ -191,7 +191,7 @@ impl ReaderHistorySearch {
}
/// Attempt to append matches from the current history item.
/// \return true if something was appended.
/// Return true if something was appended.
fn append_matches_from_search(&mut self) -> bool {
fn find(zelf: &ReaderHistorySearch, haystack: &wstr, needle: &wstr) -> Option<usize> {
if zelf.search().ignores_case() {

8
src/redirection.rs
View File

@ -73,7 +73,7 @@ impl RedirectionSpec {
pub fn new(fd: RawFd, mode: RedirectionMode, target: WString) -> Self {
Self { fd, mode, target }
}
/// \return if this is a close-type redirection.
/// Return if this is a close-type redirection.
pub fn is_close(&self) -> bool {
self.mode == RedirectionMode::fd && self.target == "-"
}
@ -83,7 +83,7 @@ impl RedirectionSpec {
fish_wcstoi(&self.target).ok()
}
/// \return the open flags for this redirection.
/// Return the open flags for this redirection.
pub fn oflags(&self) -> OFlag {
match self.mode.oflags() {
Some(flags) => flags,
@ -113,12 +113,12 @@ impl Dup2List {
pub fn new() -> Self {
Default::default()
}
/// \return the list of dup2 actions.
/// Return the list of dup2 actions.
pub fn get_actions(&self) -> &[Dup2Action] {
&self.actions
}
/// \return the fd ultimately dup'd to a target fd, or -1 if the target is closed.
/// Return the fd ultimately dup'd to a target fd, or -1 if the target is closed.
/// For example, if target fd is 1, and we have a dup2 chain 5->3 and 3->1, then we will
/// return 5. If the target is not referenced in the chain, returns target.
pub fn fd_for_target_fd(&self, target: RawFd) -> RawFd {

22
src/screen.rs
View File

@ -76,17 +76,17 @@ impl Line {
}
}
/// \return the number of characters.
/// Return the number of characters.
pub fn len(&self) -> usize {
self.text.len()
}
/// \return the character at a char index.
/// Return the character at a char index.
pub fn char_at(&self, idx: usize) -> char {
self.text[idx].character
}
/// \return the color at a char index.
/// Return the color at a char index.
pub fn color_at(&self, idx: usize) -> HighlightSpec {
self.text[idx].highlight
}
@ -96,7 +96,7 @@ impl Line {
self.text.extend_from_slice(&line.text);
}
/// \return the width of this line, counting up to no more than `max` characters.
/// Return the width of this line, counting up to no more than `max` characters.
/// This follows fish_wcswidth() semantics, except that characters whose width would be -1 are
/// treated as 0.
pub fn wcswidth_min_0(&self, max: usize /* = usize::MAX */) -> usize {
@ -506,7 +506,7 @@ impl Screen {
}
}
/// \return whether we believe the cursor is wrapped onto the last line, and that line is
/// Return whether we believe the cursor is wrapped onto the last line, and that line is
/// otherwise empty. This includes both soft and hard wrapping.
pub fn cursor_is_wrapped_to_own_line(&self) -> bool {
// Note == comparison against the line count is correct: we do not create a line just for the
@ -1128,7 +1128,7 @@ impl LayoutCache {
pub const PROMPT_CACHE_MAX_SIZE: usize = 12;
/// \return the size of the escape code cache.
/// Return the size of the escape code cache.
pub fn esc_cache_size(&self) -> usize {
self.esc_cache.len()
}
@ -1140,7 +1140,7 @@ impl LayoutCache {
}
}
/// \return the length of an escape code, accessing and perhaps populating the cache.
/// Return the length of an escape code, accessing and perhaps populating the cache.
pub fn escape_code_length(&mut self, code: &wstr) -> usize {
if code.char_at(0) != '\x1B' {
return 0;
@ -1158,7 +1158,7 @@ impl LayoutCache {
esc_seq_len
}
/// \return the length of a string that matches a prefix of `entry`.
/// Return the length of a string that matches a prefix of `entry`.
pub fn find_escape_code(&self, entry: &wstr) -> usize {
// Do a binary search and see if the escape code right before our entry is a prefix of our
// entry. Note this assumes that escape codes are prefix-free: no escape code is a prefix of
@ -1178,7 +1178,7 @@ impl LayoutCache {
}
/// Computes a prompt layout for `prompt_str`, perhaps truncating it to `max_line_width`.
/// \return the layout, and optionally the truncated prompt itself, by reference.
/// Return the layout, and optionally the truncated prompt itself, by reference.
pub fn calc_prompt_layout(
&mut self,
prompt_str: &wstr,
@ -1494,7 +1494,7 @@ fn is_visual_escape_seq(code: &wstr) -> Option<usize> {
None
}
/// \return whether `c` ends a measuring run.
/// Return whether `c` ends a measuring run.
fn is_run_terminator(c: char) -> bool {
matches!(c, '\0' | '\n' | '\r' | '\x0C')
}
@ -1533,7 +1533,7 @@ fn measure_run_from(
}
/// Attempt to truncate the prompt run `run`, which has width `width`, to `no` more than
/// desired_width. \return the resulting width and run by reference.
/// desired_width. Return the resulting width and run by reference.
fn truncate_run(
run: &mut WString,
desired_width: usize,

4
src/signal.rs
View File

@ -18,7 +18,7 @@ static MAIN_PID: AtomicI32 = AtomicI32::new(0);
/// It's possible that we receive a signal after we have forked, but before we have reset the signal
/// handlers (or even run the pthread_atfork calls). In that event we will do something dumb like
/// swallow SIGINT. Ensure that doesn't happen. Check if we are the main fish process; if not, reset
/// and re-raise the signal. \return whether we re-raised the signal.
/// and re-raise the signal. Return whether we re-raised the signal.
fn reraise_if_forked_child(sig: i32) -> bool {
// Don't use is_forked_child: it relies on atfork handlers which may have not yet run.
if getpid() == MAIN_PID.load(Ordering::Relaxed) {
@ -43,7 +43,7 @@ pub fn signal_clear_cancel() {
CANCELLATION_SIGNAL.store(0, Ordering::Relaxed);
}
/// \return the most recent cancellation signal received by the fish process.
/// Return the most recent cancellation signal received by the fish process.
/// Currently only SIGINT is considered a cancellation signal.
/// This is thread safe.
pub fn signal_check_cancel() -> i32 {

8
src/termsize.rs
View File

@ -36,7 +36,7 @@ fn var_to_int_or(var: Option<EnvVar>, default: isize) -> isize {
default
}
/// \return a termsize from ioctl, or None on error or if not supported.
/// Return a termsize from ioctl, or None on error or if not supported.
fn read_termsize_from_tty() -> Option<Termsize> {
let mut ret: Option<Termsize> = None;
// Note: historically we've supported libc::winsize not existing.
@ -101,7 +101,7 @@ impl TermsizeData {
}
}
/// \return the current termsize from this data.
/// Return the current termsize from this data.
fn current(&self) -> Termsize {
// This encapsulates our ordering logic. If we have a termsize from a tty, use it; otherwise use
// what we have seen from the environment.
@ -139,7 +139,7 @@ pub struct TermsizeContainer {
}
impl TermsizeContainer {
/// \return the termsize without applying any updates.
/// Return the termsize without applying any updates.
/// Return the default termsize if none.
pub fn last(&self) -> Termsize {
self.data.lock().unwrap().current()
@ -167,7 +167,7 @@ impl TermsizeContainer {
/// If our termsize is stale, update it, using `parser` to fire any events that may be
/// registered for COLUMNS and LINES.
/// This requires a shared reference so it can work from a static.
/// \return the updated termsize.
/// Return the updated termsize.
pub fn updating(&self, parser: &Parser) -> Termsize {
let new_size;
let prev_size;

8
src/tokenizer.rs
View File

@ -877,7 +877,7 @@ pub fn is_token_delimiter(c: char, next: Option<char>) -> bool {
c == '(' || !tok_is_string_character(c, next)
}
/// \return the first token from the string, skipping variable assignments like A=B.
/// Return the first token from the string, skipping variable assignments like A=B.
pub fn tok_command(str: &wstr) -> WString {
let mut t = Tokenizer::new(str, TokFlags(0));
while let Some(token) = t.next() {
@ -1062,18 +1062,18 @@ impl TryFrom<&wstr> for PipeOrRedir {
}
impl PipeOrRedir {
/// \return the oflags (as in open(2)) for this redirection.
/// Return the oflags (as in open(2)) for this redirection.
pub fn oflags(&self) -> Option<OFlag> {
self.mode.oflags()
}
// \return if we are "valid". Here "valid" means only that the source fd did not overflow.
// Return if we are "valid". Here "valid" means only that the source fd did not overflow.
// For example 99999999999> is invalid.
pub fn is_valid(&self) -> bool {
self.fd >= 0
}
// \return the token type for this redirection.
// Return the token type for this redirection.
pub fn token_type(&self) -> TokenType {
if self.is_pipe {
TokenType::pipe

16
src/topic_monitor.rs
View File

@ -111,7 +111,7 @@ impl GenerationsList {
}
}
/// \return the value for a topic.
/// Return the value for a topic.
pub fn get(&self, topic: topic_t) -> generation_t {
match topic {
topic_t::sighupint => self.sighupint.get(),
@ -120,7 +120,7 @@ impl GenerationsList {
}
}
/// \return ourselves as an array.
/// Return ourselves as an array.
pub fn as_array(&self) -> [generation_t; 3] {
[
self.sighupint.get(),
@ -136,12 +136,12 @@ impl GenerationsList {
}
}
/// \return whether a topic is valid.
/// Return whether a topic is valid.
pub fn is_valid(&self, topic: topic_t) -> bool {
self.get(topic) != INVALID_GENERATION
}
/// \return whether any topic is valid.
/// Return whether any topic is valid.
pub fn any_valid(&self) -> bool {
let mut valid = false;
for gen in self.as_array() {
@ -398,7 +398,7 @@ impl topic_monitor_t {
/// Apply any pending updates to the data.
/// This accepts data because it must be locked.
/// \return the updated generation list.
/// Return the updated generation list.
fn updated_gens_in_data(&self, data: &mut MutexGuard<data_t>) -> GenerationsList {
// Atomically acquire the pending updates, swapping in 0.
// If there are no pending updates (likely) or a thread is waiting, just return.
@ -439,7 +439,7 @@ impl topic_monitor_t {
return data.current.clone();
}
/// \return the current generation list, opportunistically applying any pending updates.
/// Return the current generation list, opportunistically applying any pending updates.
fn updated_gens(&self) -> GenerationsList {
let mut data = self.data_.lock().unwrap();
return self.updated_gens_in_data(&mut data);
@ -517,7 +517,7 @@ impl topic_monitor_t {
}
/// Wait for some entry in the list of generations to change.
/// \return the new gens.
/// Return the new gens.
fn await_gens(&self, input_gens: &GenerationsList) -> GenerationsList {
let mut gens = input_gens.clone();
while &gens == input_gens {
@ -550,7 +550,7 @@ impl topic_monitor_t {
/// For each valid topic in `gens`, check to see if the current topic is larger than
/// the value in `gens`.
/// If `wait` is set, then wait if there are no changes; otherwise return immediately.
/// \return true if some topic changed, false if none did.
/// Return true if some topic changed, false if none did.
/// On a true return, this updates the generation list `gens`.
pub fn check(&self, gens: &GenerationsList, wait: bool) -> bool {
if !gens.any_valid() {

6
src/wait_handle.rs
View File

@ -25,7 +25,7 @@ pub struct WaitHandle {
}
impl WaitHandle {
/// \return true if this wait handle is completed.
/// Return true if this wait handle is completed.
pub fn is_completed(&self) -> bool {
self.status.get().is_some()
}
@ -34,7 +34,7 @@ impl WaitHandle {
self.status.set(Some(status));
}
/// \return the status, or None if not yet completed.
/// Return the status, or None if not yet completed.
pub fn status(&self) -> Option<i32> {
self.status.get()
}
@ -82,7 +82,7 @@ impl WaitHandleStore {
self.cache.put(wh.pid, wh);
}
/// \return the wait handle for a pid, or None if there is none.
/// Return the wait handle for a pid, or None if there is none.
/// This is a fast lookup.
pub fn get_by_pid(&self, pid: pid_t) -> Option<WaitHandleRef> {
self.cache.peek(&pid).cloned()

10
src/wchar_ext.rs
View File

@ -148,7 +148,7 @@ impl<'a> IntoCharIter for CharsUtf32<'a> {
}
}
/// \return true if `prefix` is a prefix of `contents`.
/// Return true if `prefix` is a prefix of `contents`.
fn iter_prefixes_iter<Prefix, Contents>(prefix: Prefix, mut contents: Contents) -> bool
where
Prefix: Iterator,
@ -235,7 +235,7 @@ pub trait WExt {
}
}
/// \return an iterator over substrings, split by a given char.
/// Return an iterator over substrings, split by a given char.
/// The split char is not included in the substrings.
fn split(&self, c: char) -> WStrCharSplitIter {
WStrCharSplitIter {
@ -262,7 +262,7 @@ pub trait WExt {
WString::from_chars(s)
}
/// \return the index of the first occurrence of the given char, or None.
/// Return the index of the first occurrence of the given char, or None.
fn find_char(&self, c: char) -> Option<usize> {
self.as_char_slice().iter().position(|&x| x == c)
}
@ -271,7 +271,7 @@ pub trait WExt {
self.as_char_slice().iter().any(|&x| x == c)
}
/// \return whether we start with a given Prefix.
/// Return whether we start with a given Prefix.
/// The Prefix can be a char, a &str, a &wstr, or a &WString.
fn starts_with<Prefix: IntoCharIter>(&self, prefix: Prefix) -> bool {
iter_prefixes_iter(prefix.chars(), self.as_char_slice().iter().copied())
@ -284,7 +284,7 @@ pub trait WExt {
.then(|| self.slice_from(prefix_len))
}
/// \return whether we end with a given Suffix.
/// Return whether we end with a given Suffix.
/// The Suffix can be a char, a &str, a &wstr, or a &WString.
fn ends_with<Suffix: IntoCharIter>(&self, suffix: Suffix) -> bool {
iter_prefixes_iter(

12
src/wcstringutil.rs
View File

@ -73,7 +73,7 @@ pub fn subsequence_in_string(needle: &wstr, haystack: &wstr) -> bool {
/// Case-insensitive string search, modeled after std::string::find().
/// \param fuzzy indicates this is being used for fuzzy matching and case insensitivity is
/// expanded to include symbolic characters (#3584).
/// \return the offset of the first case-insensitive matching instance of `needle` within
/// Return the offset of the first case-insensitive matching instance of `needle` within
/// `haystack`, or `string::npos()` if no results were found.
pub fn ifind(haystack: &wstr, needle: &wstr, fuzzy: bool /* = false */) -> Option<usize> {
if needle.is_empty() {
@ -140,15 +140,15 @@ impl StringFuzzyMatch {
pub fn exact_match() -> Self {
Self::new(ContainType::exact, CaseFold::samecase)
}
/// \return whether this is a samecase exact match.
/// Return whether this is a samecase exact match.
pub fn is_samecase_exact(&self) -> bool {
self.typ == ContainType::exact && self.case_fold == CaseFold::samecase
}
/// \return if we are exact or prefix match.
/// Return if we are exact or prefix match.
pub fn is_exact_or_prefix(&self) -> bool {
matches!(self.typ, ContainType::exact | ContainType::prefix)
}
// \return if our match requires a full replacement, i.e. is not a strict extension of our
// Return if our match requires a full replacement, i.e. is not a strict extension of our
// existing string. This is false only if our case matches, and our type is prefix or exact.
pub fn requires_full_replacement(&self) -> bool {
if self.case_fold != CaseFold::samecase {
@ -274,7 +274,7 @@ pub fn string_fuzzy_match_string(
/// Implementation of wcs2string that accepts a callback.
/// This invokes `func` with (const char*, size_t) pairs.
/// If `func` returns false, it stops; otherwise it continues.
/// \return false if the callback returned false, otherwise true.
/// Return false if the callback returned false, otherwise true.
pub fn wcs2string_callback(input: &wstr, mut func: impl FnMut(&[u8]) -> bool) -> bool {
let mut state = zero_mbstate();
let mut converted = [0_u8; AT_LEAST_MB_LEN_MAX];
@ -488,7 +488,7 @@ pub fn trim(input: WString, any_of: Option<&wstr>) -> WString {
result.split_off(prefix)
}
/// \return the number of escaping backslashes before a character.
/// Return the number of escaping backslashes before a character.
/// `idx` may be "one past the end."
pub fn count_preceding_backslashes(text: &wstr, idx: usize) -> usize {
assert!(idx <= text.len(), "Out of bounds");

2
src/wildcard.rs
View File

@ -1096,7 +1096,7 @@ pub fn wildcard_expand_string<'closure>(
/// \param leading_dots_fail_to_match if set, strings with leading dots are assumed to be hidden
/// files and are not matched (default was false)
///
/// \return true if the wildcard matched
/// Return true if the wildcard matched
#[must_use]
pub fn wildcard_match(
name: impl AsRef<wstr>,

12
src/wutil/dir_iter.rs
View File

@ -51,12 +51,12 @@ pub struct DirEntry {
}
impl DirEntry {
/// \return the type of this entry if it is already available, otherwise none().
/// Return the type of this entry if it is already available, otherwise none().
pub fn fast_type(&self) -> Option<DirEntryType> {
self.typ.get()
}
/// \return the type of this entry, falling back to stat() if necessary.
/// Return the type of this entry, falling back to stat() if necessary.
/// If stat() fails because the file has disappeared, this will return none().
/// If stat() fails because of a broken symlink, this will return type lnk.
pub fn check_type(&self) -> Option<DirEntryType> {
@ -67,16 +67,16 @@ impl DirEntry {
self.typ.get()
}
/// \return whether this is a directory. This may call stat().
/// Return whether this is a directory. This may call stat().
pub fn is_dir(&self) -> bool {
self.check_type() == Some(DirEntryType::dir)
}
/// \return false if we know this can't be a link via d_type, true if it could be.
/// Return false if we know this can't be a link via d_type, true if it could be.
pub fn is_possible_link(&self) -> Option<bool> {
self.possible_link
}
/// \return the stat buff for this entry, invoking stat() if necessary.
/// Return the stat buff for this entry, invoking stat() if necessary.
pub fn stat(&self) -> Option<libc::stat> {
if self.stat.get().is_none() {
self.do_stat();
@ -231,7 +231,7 @@ impl DirIter {
})
}
/// \return the underlying file descriptor.
/// Return the underlying file descriptor.
pub fn fd(&self) -> RawFd {
self.dir.fd()
}

6
src/wutil/mod.rs
View File

@ -407,7 +407,7 @@ pub fn write_to_fd(input: &[u8], fd: RawFd) -> nix::Result<usize> {
/// Write a wide string to a file descriptor. This avoids doing any additional allocation.
/// This does NOT retry on EINTR or EAGAIN, it simply returns.
/// \return -1 on error in which case errno will have been set. In this event, the number of bytes
/// Return -1 on error in which case errno will have been set. In this event, the number of bytes
/// actually written cannot be obtained.
pub fn wwrite_to_fd(input: &wstr, fd: RawFd) -> Option<usize> {
// Accumulate data in a local buffer.
@ -416,7 +416,7 @@ pub fn wwrite_to_fd(input: &wstr, fd: RawFd) -> Option<usize> {
let maxaccum: usize = std::mem::size_of_val(&accum);
// Helper to perform a write to 'fd', looping as necessary.
// \return true on success, false on error.
// Return true on success, false on error.
let mut total_written = 0;
fn do_write(fd: RawFd, total_written: &mut usize, mut buf: &[u8]) -> bool {
@ -550,7 +550,7 @@ impl FileId {
result
}
/// \return true if \param rhs has higher mtime seconds than this file_id_t.
/// Return true if \param rhs has higher mtime seconds than this file_id_t.
/// If identical, nanoseconds are compared.
pub fn older_than(&self, rhs: &FileId) -> bool {
let lhs = (self.mod_seconds, self.mod_nanoseconds);