From 8be46f3d16fc4c3b05d927aa1e9738ac865a266e Mon Sep 17 00:00:00 2001
From: Russell Brinson <57331546+rbrins@users.noreply.github.com>
Date: Wed, 11 Jan 2023 12:20:39 -0500
Subject: parseopt.nim documentation clarity - default values & cmdEnd in
 getopt (#21047)

parseopt.nim documentation clarity

Added example for default values to cmd line parameters.
Additionally, added lines in getopt documentation about case switching still requiring the `cmdEnd` kind. Hopefully this clears up any vagueness for those following along in the example but omitting the `cmdEnd` in the case because the documentation said it wasn't needed.
---
 lib/pure/parseopt.nim | 29 +++++++++++++++++++++++++++--
 1 file changed, 27 insertions(+), 2 deletions(-)

(limited to 'lib/pure/parseopt.nim')

diff --git a/lib/pure/parseopt.nim b/lib/pure/parseopt.nim
index f8d03e092..9052067db 100644
--- a/lib/pure/parseopt.nim
+++ b/lib/pure/parseopt.nim
@@ -74,7 +74,28 @@
 ##
 ## The `getopt iterator<#getopt.i,OptParser>`_, which is provided for
 ## convenience, can be used to iterate through all command line options as well.
+## 
+## To set a default value for a variable assigned through `getopt` and accept arguments from the cmd line.
+## Assign the default value to a variable before parsing. 
+## Then set the variable to the new value while parsing.
 ##
+## Here is an example:
+## .. code-block::
+##   import std/parseopt
+##
+##   var varName: string = "defaultValue"
+##   
+##   for kind, key, val in getopt():
+##     case kind
+##     of cmdArgument:
+##       discard
+##     of cmdLongOption, cmdShortOption:
+##       case key:
+##       of "varName": # --varName:<value> in the console when executing
+##         varName = val # do input sanitization in production systems
+##     of cmdEnd:
+##       discard
+## 
 ## `shortNoVal` and `longNoVal`
 ## ============================
 ##
@@ -210,6 +231,8 @@ proc initOptParser*(cmdline = "", shortNoVal: set[char] = {},
   ## parameters<#nimshortnoval-and-nimlongnoval>`_ for more information on
   ## how this affects parsing.
   ##
+  ## This does not provide a way of passing default values to arguments. 
+  ##
   ## See also:
   ## * `getopt iterator<#getopt.i,OptParser>`_
   runnableExamples:
@@ -403,7 +426,8 @@ iterator getopt*(p: var OptParser): tuple[kind: CmdLineKind, key,
   ## Convenience iterator for iterating over the given
   ## `OptParser<#OptParser>`_.
   ##
-  ## There is no need to check for `cmdEnd` while iterating.
+  ## There is no need to check for `cmdEnd` while iterating. If using `getopt` 
+  ## with case switching, checking for `cmdEnd` is required.
   ##
   ## See also:
   ## * `initOptParser proc<#initOptParser,string,set[char],seq[string]>`_
@@ -451,7 +475,8 @@ iterator getopt*(cmdline: seq[string] = @[],
   ## parameters<#nimshortnoval-and-nimlongnoval>`_ for more information on
   ## how this affects parsing.
   ##
-  ## There is no need to check for `cmdEnd` while iterating.
+  ## There is no need to check for `cmdEnd` while iterating. If using `getopt` 
+  ## with case switching, checking for `cmdEnd` is required.
   ##
   ## See also:
   ## * `initOptParser proc<#initOptParser,seq[string],set[char],seq[string]>`_
-- 
cgit 1.4.1-2-gfad0