setup_environment: code shrink
run_shell: mark as NORETURN
setup_environment, run_shell: add usage comments
login: add FIXME :(

function                                             old     new   delta
UNSPEC_print                                          64      66      +2
sulogin_main                                         509     506      -3
mkfs_minix_main                                     3070    3067      -3
login_main                                          1615    1612      -3
su_main                                              461     448     -13
setup_environment                                    261     206     -55
------------------------------------------------------------------------------
(add/remove: 0/0 grow/shrink: 1/5 up/down: 2/-77)             Total: -75 bytes
   text    data     bss     dec     hex filename
 772578    1051   10724  784353   bf7e1 busybox_old
 772502    1051   10724  784277   bf795 busybox_unstripped

diff --git a/include/libbb.h b/include/libbb.h
index a4aa90d..e5f0351 100644
--- a/include/libbb.h
+++ b/include/libbb.h
@@ -780,6 +780,7 @@
 extern void bb_do_delay(int seconds);
 extern void change_identity(const struct passwd *pw);
 extern const char *change_identity_e2str(const struct passwd *pw);
+extern void run_shell(const char *shell, int loginshell, const char *command, const char **additional_args) ATTRIBUTE_NORETURN;
 extern void run_shell(const char *shell, int loginshell, const char *command, const char **additional_args);
 #if ENABLE_SELINUX
 extern void renew_current_security_context(void);
@@ -790,6 +791,21 @@
 #endif
 extern void selinux_or_die(void);
 extern int restricted_shell(const char *shell);
+
+/* setup_environment:
+ * if loginshell = 1: cd(pw->pw_dir), clear environment, then set
+ *   TERM=(old value)
+ *   USER=pw->pw_name, LOGNAME=pw->pw_name
+ *   PATH=bb_default_[root_]path
+ *   HOME=pw->pw_dir
+ *   SHELL=shell
+ * else if changeenv = 1:
+ *   if not root (if pw->pw_uid != 0):
+ *     USER=pw->pw_name, LOGNAME=pw->pw_name
+ *   HOME=pw->pw_dir
+ *   SHELL=shell
+ * else does nothing
+ */
 extern void setup_environment(const char *shell, int loginshell, int changeenv, const struct passwd *pw);
 extern int correct_password(const struct passwd *pw);
 /* Returns a ptr to static storage */