From 8b01ea4434cde4eea9c09308cec72867aba50264 Mon Sep 17 00:00:00 2001
From: Gregory Nutt <gnutt@nuttx.org>
Date: Tue, 2 Oct 2018 06:53:16 -0600
Subject: [PATCH] Update a README/Improve some C comments.

---
 nshlib/README.txt    | 49 +++++++++++++++++++++++++++++---------------
 nshlib/nsh_envcmds.c |  9 +++++++-
 2 files changed, 41 insertions(+), 17 deletions(-)

diff --git a/nshlib/README.txt b/nshlib/README.txt
index 4ef09c339..2630c46ef 100644
--- a/nshlib/README.txt
+++ b/nshlib/README.txt
@@ -520,25 +520,32 @@ o export <name> [<value>]
 
   1. Using 'export' to promote an NSH variable to an environment variable.
 
-    nsh> env
-    PATH=/bin
+       nsh> env
+       PATH=/bin
 
-    nsh> set foo bar
-    nsh> env
-    PATH=/bin
+       nsh> set foo bar
+       nsh> env
+       PATH=/bin
 
-    nsh> export foo
-    nsh> env
-    PATH=/bin
-    foo=bar
+       nsh> export foo
+       nsh> env
+       PATH=/bin
+       foo=bar
+
+     A group-wide environment variable is created with the same value as the
+     local NSH variable; the local NSH variable is removed.
+
+     NOTE: This behavior differs from the Bash shell.  Bash will retain the
+     local Bash variable which will shadow the environment variable of the
+     same name.
 
   2. Using 'export' to set an environment variable
 
-    nsh> export dog poop
-    nsh> env
-    PATH=/bin
-    foo=bar
-    dog=poop
+       nsh> export dog poop
+       nsh> env
+       PATH=/bin
+       foo=bar
+       dog=poop
 
   The export command is not supported by NSH unless both CONFIG_NSH_VARS=y
   and CONFIG_DISABLE_ENVIRON is not set.
@@ -1116,8 +1123,18 @@ o set [{+|-}{e|x|xe|ex}] [<name> <value>]
     foovalue
     nsh>
 
-  If CONFIG_NSH_VARS is set, the effect of this 'set' command is to set the local
-  NSH variable.  Otherwise, the group-wide environment variable will be set.
+  If CONFIG_NSH_VARS is selected, the effect of this 'set' command is to set
+  the local NSH variable.  Otherwise, the group-wide environment variable
+  will be set.
+
+  If the local NSH variable has already been 'promoted' to an environment
+  variable, then the 'set' command will set the value of the environment
+  variable rather than the local NSH variable.
+
+  NOTE:  The Bash shell does not work this way.  Bash would set the value of
+  the local Bash variable and would not modify the environment variable.
+  The local Bash variable would that then shadow the environment variable
+  with a differing value.
 
   Set the 'exit on error control' and/or 'print a trace' of commands when parsing
   scripts in NSH.  The settinngs are in effect from the point of exection, until
diff --git a/nshlib/nsh_envcmds.c b/nshlib/nsh_envcmds.c
index f7c7fec54..6f28b3200 100644
--- a/nshlib/nsh_envcmds.c
+++ b/nshlib/nsh_envcmds.c
@@ -411,6 +411,9 @@ int cmd_set(FAR struct nsh_vtbl_s *vtbl, int argc, char **argv)
 #ifndef CONFIG_DISABLE_ENVIRON
       /* Check if the NSH variable has already been promoted to an group-
        * wide environment variable.
+       *
+       * REVISIT:  Is this the correct behavior?  Bash would create/modify
+       * a local variable that shadows the environment variable.
        */
 
      oldvalue = getenv(argv[ndx]);
@@ -529,7 +532,11 @@ int cmd_export(FAR struct nsh_vtbl_s *vtbl, int argc, char **argv)
     }
   else
     {
-      /* Unset NSH variable */
+      /* Unset NSH variable.
+       *
+       * REVISIT:  Is this the correct behavior?  Bash would retain
+       * a local variable that shadows the environment variable.
+       */
 
       status = nsh_unsetvar(vtbl, argv[1]);
       if (status < 0 && status != -ENOENT)