1
0
mirror of https://github.com/vlang/v.git synced 2023-08-10 21:13:21 +03:00

docs: improve pub fn comments for the flag module

This commit is contained in:
Delyan Angelov 2022-01-18 18:38:27 +02:00
parent 1c5eb7ccdc
commit 95b0c3789f
No known key found for this signature in database
GPG Key ID: 66886C0F12D595ED

View File

@ -194,6 +194,7 @@ pub fn (mut fs FlagParser) allow_unknown_args() {
} }
// private helper to register a flag // private helper to register a flag
// This version supports abbreviations.
fn (mut fs FlagParser) add_flag(name string, abbr byte, usage string, desc string) { fn (mut fs FlagParser) add_flag(name string, abbr byte, usage string, desc string) {
fs.flags << Flag{ fs.flags << Flag{
name: name name: name
@ -308,8 +309,9 @@ fn (mut fs FlagParser) parse_bool_value(longhand string, shorthand byte) ?string
return error("parameter '$longhand' not found") return error("parameter '$longhand' not found")
} }
// bool_opt returns an optional that returns the value associated with the flag. // bool_opt returns an option with the bool value of the given command line flag, named `name`.
// In the situation that the flag was not provided, it returns null. // It returns an error, when the flag is not given by the user.
// This version supports abbreviations.
pub fn (mut fs FlagParser) bool_opt(name string, abbr byte, usage string) ?bool { pub fn (mut fs FlagParser) bool_opt(name string, abbr byte, usage string) ?bool {
mut res := false mut res := false
{ {
@ -322,20 +324,18 @@ pub fn (mut fs FlagParser) bool_opt(name string, abbr byte, usage string) ?bool
return res return res
} }
// defining and parsing a bool flag // bool defines and parses a string flag/option named `name`.
// if defined // If that flag is given by the user, then it returns its parsed bool value.
// the value is returned (true/false) // When it is not, it returns the default value in `bdefault`.
// else // This version supports abbreviations.
// the default value is returned
// version with abbr
// TODO error handling for invalid string to bool conversion
pub fn (mut fs FlagParser) bool(name string, abbr byte, bdefault bool, usage string) bool { pub fn (mut fs FlagParser) bool(name string, abbr byte, bdefault bool, usage string) bool {
value := fs.bool_opt(name, abbr, usage) or { return bdefault } value := fs.bool_opt(name, abbr, usage) or { return bdefault }
return value return value
} }
// int_multi returns all instances of values associated with the flags provided // int_multi returns all values associated with the provided flag in `name`.
// In the case that none were found, it returns an empty array. // When that flag has no values, it returns an empty array.
// This version supports abbreviations.
pub fn (mut fs FlagParser) int_multi(name string, abbr byte, usage string) []int { pub fn (mut fs FlagParser) int_multi(name string, abbr byte, usage string) []int {
fs.add_flag(name, abbr, usage, '<multiple ints>') fs.add_flag(name, abbr, usage, '<multiple ints>')
parsed := fs.parse_value(name, abbr) parsed := fs.parse_value(name, abbr)
@ -346,8 +346,9 @@ pub fn (mut fs FlagParser) int_multi(name string, abbr byte, usage string) []int
return value return value
} }
// int_opt returns an optional that returns the value associated with the flag. // int_opt returns an option with the integer value, associated with the flag in `name`.
// In the situation that the flag was not provided, it returns null. // When the flag is not given by the user, it returns an error.
// This version supports abbreviations.
pub fn (mut fs FlagParser) int_opt(name string, abbr byte, usage string) ?int { pub fn (mut fs FlagParser) int_opt(name string, abbr byte, usage string) ?int {
mut res := 0 mut res := 0
{ {
@ -362,20 +363,18 @@ pub fn (mut fs FlagParser) int_opt(name string, abbr byte, usage string) ?int {
return res return res
} }
// defining and parsing an int flag // int defines and parses an integer flag, named `name`.
// if defined // When the flag is given by the user, it returns its parsed integer value.
// the value is returned (int) // When it is not, it returns the integer value in `idefault`.
// else // This version supports abbreviations.
// the default value is returned
// version with abbr
// TODO error handling for invalid string to int conversion
pub fn (mut fs FlagParser) int(name string, abbr byte, idefault int, usage string) int { pub fn (mut fs FlagParser) int(name string, abbr byte, idefault int, usage string) int {
value := fs.int_opt(name, abbr, usage) or { return idefault } value := fs.int_opt(name, abbr, usage) or { return idefault }
return value return value
} }
// float_multi returns all instances of values associated with the flags provided // float_multi returns all floating point values, associated with the flag named `name`.
// In the case that none were found, it returns an empty array. // When no values for that flag are found, it returns an empty array.
// This version supports abbreviations.
pub fn (mut fs FlagParser) float_multi(name string, abbr byte, usage string) []f64 { pub fn (mut fs FlagParser) float_multi(name string, abbr byte, usage string) []f64 {
fs.add_flag(name, abbr, usage, '<multiple floats>') fs.add_flag(name, abbr, usage, '<multiple floats>')
parsed := fs.parse_value(name, abbr) parsed := fs.parse_value(name, abbr)
@ -386,8 +385,9 @@ pub fn (mut fs FlagParser) float_multi(name string, abbr byte, usage string) []f
return value return value
} }
// float_opt returns an optional that returns the value associated with the flag. // float_opt returns an option with the floating point value, associated with the flag in `name`.
// In the situation that the flag was not provided, it returns null. // When the flag is not given by the user, it returns an error.
// This version supports abbreviations.
pub fn (mut fs FlagParser) float_opt(name string, abbr byte, usage string) ?f64 { pub fn (mut fs FlagParser) float_opt(name string, abbr byte, usage string) ?f64 {
mut res := 0.0 mut res := 0.0
{ {
@ -401,27 +401,26 @@ pub fn (mut fs FlagParser) float_opt(name string, abbr byte, usage string) ?f64
return res return res
} }
// defining and parsing a float flag // float defines and parses a floating point flag, named `name`.
// if defined // When the flag is given by the user, it returns its parsed floating point value.
// the value is returned (float) // When it is not, it returns the value in `fdefault`.
// else // This version supports abbreviations.
// the default value is returned
// version with abbr
// TODO error handling for invalid string to float conversion
pub fn (mut fs FlagParser) float(name string, abbr byte, fdefault f64, usage string) f64 { pub fn (mut fs FlagParser) float(name string, abbr byte, fdefault f64, usage string) f64 {
value := fs.float_opt(name, abbr, usage) or { return fdefault } value := fs.float_opt(name, abbr, usage) or { return fdefault }
return value return value
} }
// string_multi returns all instances of values associated with the flags provided // string_multi returns all string values, associated with the flag named `name`.
// In the case that none were found, it returns an empty array. // When no values for that flag are found, it returns an empty array.
// This version supports abbreviations.
pub fn (mut fs FlagParser) string_multi(name string, abbr byte, usage string) []string { pub fn (mut fs FlagParser) string_multi(name string, abbr byte, usage string) []string {
fs.add_flag(name, abbr, usage, '<multiple strings>') fs.add_flag(name, abbr, usage, '<multiple strings>')
return fs.parse_value(name, abbr) return fs.parse_value(name, abbr)
} }
// string_opt returns an optional that returns the value associated with the flag. // string_opt returns an option with the string value, associated with the flag in `name`.
// In the situation that the flag was not provided, it returns null. // When the flag is not given by the user, it returns an error.
// This version supports abbreviations.
pub fn (mut fs FlagParser) string_opt(name string, abbr byte, usage string) ?string { pub fn (mut fs FlagParser) string_opt(name string, abbr byte, usage string) ?string {
mut res := '' mut res := ''
{ {
@ -435,10 +434,10 @@ pub fn (mut fs FlagParser) string_opt(name string, abbr byte, usage string) ?str
return res return res
} }
// string defines and parses a string flag/option. // string defines and parses a string flag/option, named `name`.
// If that flag is given as an option, then the parsed // If that flag is given as an option, then its parsed value is returned as a string.
// value is returned as a string. Otherwise, the default // When it is not, it returns the default string value in `sdefault`.
// value is returned. This version supports abbreviations. // This version supports abbreviations.
pub fn (mut fs FlagParser) string(name string, abbr byte, sdefault string, usage string) string { pub fn (mut fs FlagParser) string(name string, abbr byte, sdefault string, usage string) string {
value := fs.string_opt(name, abbr, usage) or { return sdefault } value := fs.string_opt(name, abbr, usage) or { return sdefault }
return value return value