From a840dae93519d15cf15578f455545189695f016f Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <eelco.dolstra@logicblox.com>
Date: Thu, 31 Oct 2013 08:41:51 +0100
Subject: [PATCH] Improve description of the users.extraUsers.*.description
 option

Fixes NixOS/nixos#278.
---
 nixos/modules/config/users-groups.nix | 22 ++++++++++++++++------
 1 file changed, 16 insertions(+), 6 deletions(-)

diff --git a/nixos/modules/config/users-groups.nix b/nixos/modules/config/users-groups.nix
index d2eca7c3dcda..fb8b0229c1da 100644
--- a/nixos/modules/config/users-groups.nix
+++ b/nixos/modules/config/users-groups.nix
@@ -19,7 +19,12 @@ let
       description = mkOption {
         type = types.str;
         default = "";
-        description = "A short description of the user account.";
+        example = "Alice Q. User";
+        description = ''
+          A short description of the user account, typically the
+          user's full name.  This is actually the “GECOS” or “comment”
+          field in <filename>/etc/passwd</filename>.
+        '';
       };
 
       uid = mkOption {
@@ -67,7 +72,13 @@ let
       password = mkOption {
         type = with types; uniq (nullOr str);
         default = null;
-        description = "The user's password. If undefined, no password is set for the user.  Warning: do not set confidential information here because this data would be readable by all.  This option should only be used for public account such as guest.";
+        description = ''
+          The user's password. If undefined, no password is set for
+          the user.  Warning: do not set confidential information here
+          because it is world-readable in the Nix store.  This option
+          should only be used for public accounts such as
+          <literal>guest</literal>.
+        '';
       };
 
       isSystemUser = mkOption {
@@ -79,11 +90,11 @@ let
       createUser = mkOption {
         type = types.bool;
         default = true;
-        description = "
+        description = ''
           Indicates if the user should be created automatically as a local user.
           Set this to false if the user for instance is an LDAP user. NixOS will
           then not modify any of the basic properties for the user account.
-        ";
+        '';
       };
 
       isAlias = mkOption {
@@ -149,13 +160,12 @@ in
       example = {
         alice = {
           uid = 1234;
-          description = "Alice";
+          description = "Alice Q. User";
           home = "/home/alice";
           createHome = true;
           group = "users";
           extraGroups = ["wheel"];
           shell = "/bin/sh";
-          password = "foobar";
         };
       };
       description = ''