From cce7486deb2be3375c0a58899af5e5ff802bf869 Mon Sep 17 00:00:00 2001
From: Craige McWhirter <craige@mcwhirter.io>
Date: Thu, 15 Aug 2019 08:29:13 +1000
Subject: [PATCH] nixos/doc: Clarify wireless examples

This commits makes it clearer to a novice reader how to configure several
diferent types of SSID connections that were otherwise obscurely documented

Resolves #66650
---
 nixos/doc/manual/configuration/wireless.xml        | 11 +++++++++--
 .../modules/services/networking/wpa_supplicant.nix | 14 ++++++++++++--
 2 files changed, 21 insertions(+), 4 deletions(-)

diff --git a/nixos/doc/manual/configuration/wireless.xml b/nixos/doc/manual/configuration/wireless.xml
index 9c0e3a8d7aa4..247d29d58314 100644
--- a/nixos/doc/manual/configuration/wireless.xml
+++ b/nixos/doc/manual/configuration/wireless.xml
@@ -19,10 +19,17 @@
   NixOS lets you specify networks for wpa_supplicant declaratively:
 <programlisting>
 <xref linkend="opt-networking.wireless.networks"/> = {
-  echelon = {
+  echelon = {                # SSID with no spaces or special characters
     psk = "abcdefgh";
   };
-  "free.wifi" = {};
+  "echelon's AP" = {         # SSID with spaces and/or special characters
+    psk = "ijklmnop";
+  };
+  echelon = {                # Hidden SSID
+    hidden = true;
+    psk = "qrstuvwx";
+  };
+  free.wifi = {};            # Public wireless network
 };
 </programlisting>
   Be aware that keys will be written to the nix store in plaintext! When no
diff --git a/nixos/modules/services/networking/wpa_supplicant.nix b/nixos/modules/services/networking/wpa_supplicant.nix
index 63e59e7c8fac..294c0d70edea 100644
--- a/nixos/modules/services/networking/wpa_supplicant.nix
+++ b/nixos/modules/services/networking/wpa_supplicant.nix
@@ -103,6 +103,13 @@ in {
               description = ''
                 Set this to <literal>true</literal> if the SSID of the network is hidden.
               '';
+              example = literalExample ''
+                { echelon = {
+                    hidden = true;
+                    psk = "abcdefgh";
+                  };
+                }
+              '';
             };
 
             priority = mkOption {
@@ -146,10 +153,13 @@ in {
         '';
         default = {};
         example = literalExample ''
-          { echelon = {
+          { echelon = {                   # SSID with no spaces or special characters
               psk = "abcdefgh";
             };
-            "free.wifi" = {};
+            "echelon's AP" = {            # SSID with spaces and/or special characters
+               psk = "ijklmnop";
+            };
+            "free.wifi" = {};             # Public wireless network
           }
         '';
       };