From b9fa7457c2011130b28f5eca063f88bdf72be544 Mon Sep 17 00:00:00 2001 From: acdenisSK Date: Fri, 6 Apr 2018 21:36:57 +0200 Subject: [PATCH] Improve docs for `Args` --- src/framework/standard/args.rs | 55 ++++++++++++++++++++++------------ 1 file changed, 36 insertions(+), 19 deletions(-) diff --git a/src/framework/standard/args.rs b/src/framework/standard/args.rs index 928715ba689..6d37822c0c4 100644 --- a/src/framework/standard/args.rs +++ b/src/framework/standard/args.rs @@ -131,8 +131,17 @@ fn parse(s: &mut String, delimiters: &[String]) -> Result /// A utility struct for handling arguments of a command. /// -/// General functionality is done via removing an item, parsing it, then returning it; this however -/// can be mitigated with the `*_n` methods, which just parse and return. +/// An "argument" is a part of the message up until the end of the message or at one of the specified delimiters. +/// (E.g.: delim: " ", message: "ab cd"; 1th arg is "ab") +/// +/// The general functionality provided by this struct is to not only make arguments convenient to handle, +/// but to handle parsing them to a specifc type as well. +/// +/// Majority of the methods here remove the argument as to advance to further arguments. +/// If you do not wish for this behaviour, use the suffixed `*_n` methods instead. +/// +/// `Args` provides parsing arguments inside quotes too (for which case, delimiters don't matter), via the suffixed `*_quoted` methods. +/// *note: these fall back to the normal methods' behaviour if the quotes are malformed; i.e missing an opening or closing quote* #[derive(Clone, Debug)] pub struct Args { delimiters: Vec, @@ -153,7 +162,7 @@ impl Args { } } - /// Removes the first element, parses it to a specific type if necessary, returns. + /// Parses the current argument and advances. /// /// # Examples /// @@ -163,7 +172,7 @@ impl Args { /// let mut args = Args::new("42 69", &[" ".to_string()]); /// /// assert_eq!(args.single::().unwrap(), 42); - /// assert_eq!(args, "69"); + /// assert_eq!(args.full(), "69"); /// ``` pub fn single(&mut self) -> Result where T::Err: StdError { @@ -178,7 +187,7 @@ impl Args { parse::(&mut self.message, &self.delimiters) } - /// Like [`single`], but doesn't remove the element. + /// Like [`single`], but doesn't advance. /// /// # Examples /// @@ -197,7 +206,7 @@ impl Args { parse::(&mut self.message.clone(), &self.delimiters) } - /// Accesses the current state of the internal string. + /// Accesses the current state of the internally-stored message. /// /// # Examples /// @@ -210,9 +219,9 @@ impl Args { /// ``` pub fn full(&self) -> &str { &self.message } - /// Accesses the current state of the internal string, but - /// with quotes removed if it has both opening and closing quotes; - /// otherwise returns the string as is. + /// Accesses the current state of the internally-stored message, + /// removing quotes if it contains the opening and closing ones, + /// but otherwise returns the string as is. /// /// # Examples /// @@ -305,7 +314,7 @@ impl Args { self.message.is_empty() } - /// Like [`len`], but takes quotes into account. + /// Like [`len`], but accounts quotes. /// /// # Examples /// @@ -332,7 +341,9 @@ impl Args { } } - /// Skips if there's a first element, but also returns it. + /// Returns the argument as a string (thus sort-of skipping it). + /// + /// *This is sugar for `args.single::().ok()`* /// /// # Examples /// @@ -361,6 +372,7 @@ impl Args { /// Like [`skip`], but allows for multiple at once. /// /// # Examples + /// /// ```rust /// use serenity::framework::standard::Args; /// @@ -394,7 +406,7 @@ impl Args { Some(vec) } - /// Like [`single`], but takes quotes into account. + /// Like [`single`], but accounts quotes. /// /// # Examples /// @@ -421,7 +433,7 @@ impl Args { parse_quotes::(&mut self.message, &self.delimiters) } - /// Like [`single_quoted`], but doesn't remove the element. + /// Like [`single_quoted`], but doesn't advance. /// /// # Examples /// @@ -440,7 +452,7 @@ impl Args { parse_quotes::(&mut self.message.clone(), &self.delimiters) } - /// Like [`multiple`], but takes quotes into account. + /// Like [`multiple`], but accounts quotes. /// /// # Examples /// @@ -462,7 +474,7 @@ impl Args { self.iter_quoted::().collect() } - /// Like [`iter`], but takes quotes into account + /// Like [`iter`], but accounts quotes. /// /// # Examples /// @@ -481,7 +493,9 @@ impl Args { IterQuoted::new(self) } - /// Empty outs the internal vector while parsing (if necessary) and returning them. + /// This is a convenience function for parsing until the end of the message and returning the parsed results in a `Vec`. + /// + /// *This is sugar for `args.iter().collect::>()`* /// /// # Examples /// @@ -501,7 +515,7 @@ impl Args { self.iter::().collect() } - /// Provides an iterator of items: (`T: FromStr`) `Result`. + /// Provides an arguments iterator up until the end of the message. /// /// # Examples /// @@ -518,7 +532,8 @@ impl Args { Iter::new(self) } - /// Returns the first argument that can be converted and removes it from the list. + /// Returns the first argument that can be parsed and removes it from the message. The suitable argument + /// can be in an arbitrary position in the message. /// /// **Note**: This replaces all delimiters within the message /// by the first set in your framework-config to win performance. @@ -576,7 +591,7 @@ impl Args { } } - /// Returns the first argument that can be converted and does not remove it from the list. + /// Like [`find`], but does not remove it. /// /// # Examples /// @@ -588,6 +603,8 @@ impl Args { /// assert_eq!(args.find_n::().unwrap(), 69); /// assert_eq!(args.full(), "c47 69"); /// ``` + /// + /// [`find`]: #method.find pub fn find_n(&mut self) -> Result where T::Err: StdError { // Same here.