From 10210bd10136739232f0d4f8fb448533bbc23c7c Mon Sep 17 00:00:00 2001
From: Jakub Rzeszutko <jakub.rzeszutko@nordicsemi.no>
Date: Thu, 1 Jul 2021 11:40:14 +0200
Subject: [PATCH] doc: shell getopt support

Documentations has been updated acorcing to changes in the getopt
library.

Signed-off-by: Jakub Rzeszutko <jakub.rzeszutko@nordicsemi.no>
---
 doc/reference/shell/index.rst | 49 ++++++++++++++++++++++++++++-------
 1 file changed, 39 insertions(+), 10 deletions(-)

diff --git a/doc/reference/shell/index.rst b/doc/reference/shell/index.rst
index 231f3d34274..0d014520010 100644
--- a/doc/reference/shell/index.rst
+++ b/doc/reference/shell/index.rst
@@ -30,7 +30,7 @@ interaction is required. This module is a Unix-like shell with these features:
 * Built-in handler to display help for the commands.
 * Support for wildcards: ``*`` and ``?``.
 * Support for meta keys.
-* Support for getopt.
+* Support for getopt and getopt_long.
 * Kconfig configuration to optimize memory usage.
 
 .. note::
@@ -486,22 +486,51 @@ Getopt Feature
 
 Some shell users apart from subcommands might need to use options as well.
 the arguments string, looking for supported options. Typically, this task
-is accomplished by the ``getopt`` function.
+is accomplished by the ``getopt`` familly functions.
 
-For this purpose shell supports the getopt library available
-in the FreeBSD project. I was modified so that it can be used
-by all instances of the shell at the same time, hence its call requires
-one more parameter.
+For this purpose shell supports the getopt and getopt_long libraries available
+in the FreeBSD project. This feature is activated by:
+:kconfig:`CONFIG_GETOPT` set to ``y`` and :kconfig:`CONFIG_GETOPT_LONG`
+set to ``y``.
 
-An example usage:
+This feature can be used in thread safe as well as non thread safe manner.
+The former is full compatible with regular getopt usage while the latter
+a bit differs.
+
+An example non-thread safe usage:
 
 .. code-block:: c
 
-  while ((char c = shell_getopt(shell, argc, argv, "abhc:")) != -1) {
-     /* some code */
+  char *cvalue = NULL;
+  while ((char c = getopt(argc, argv, "abhc:")) != -1) {
+        switch (c) {
+        case 'c':
+                cvalue = optarg;
+                break;
+        default:
+                break;
+        }
   }
 
-This module is activated by :kconfig:`CONFIG_SHELL_GETOPT` set to ``y``.
+An example thread safe usage:
+
+.. code-block:: c
+
+  char *cvalue = NULL;
+  struct getopt_state *state;
+  while ((char c = getopt(argc, argv, "abhc:")) != -1) {
+        state = getopt_state_get();
+        switch (c) {
+        case 'c':
+                cvalue = state->optarg;
+                break;
+        default:
+                break;
+        }
+  }
+
+Thread safe getopt functionality is activated by
+:kconfig:`CONFIG_SHELL_GETOPT` set to ``y``.
 
 Obscured Input Feature
 **********************