docs: explain secrets flags in settings specification

docs/api/generate-settings-spec.c

@@ -124,6 +124,7 @@ write_one_setting (FILE *f, SettingNewFunc func)
 		char *default_value;
 		TypeNameElement *name_iter;
 		GValue value = { 0, };
+		char *flags_str = NULL;
 
 		value_type = g_type_name (G_PARAM_SPEC_VALUE_TYPE (*iter));
 		for (name_iter = &name_map[0]; name_iter && name_iter->gvalue_name; name_iter++) {
@@ -150,15 +151,23 @@ write_one_setting (FILE *f, SettingNewFunc func)
 			g_object_get (G_OBJECT (s), NM_SETTING_NAME, &default_value, NULL);
 		}
 
+		if (g_str_has_suffix (key_name, "-flags"))
+			flags_str = g_strdup_printf (" (see <xref linkend=\"secrets-flags\"/> for flag values)");
+
 		(void) fprintf (f,
 			"      <row>\n"
 			"        <entry><screen>%s</screen></entry>\n"
 			"        <entry><screen>%s</screen></entry>\n"
 			"        <entry><screen>%s</screen></entry>\n"
-			"        <entry>%s</entry>\n"
+			"        <entry>%s%s</entry>\n"
 			"      </row>\n",
-			key_name, value_type, default_value ? default_value : "", value_desc);
+			key_name,
+			value_type,
+			default_value ? default_value : "",
+			value_desc,
+			flags_str ? flags_str : "");
 
+		g_free (flags_str);
 		g_free (default_value);
 	}
 
@@ -202,7 +211,7 @@ main (int argc, char *argv[])
 		"<!ENTITY %% local.common.attrib \"xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'\">"
 		"]>"
 		"<section>\n"
-		"  <title>NetworkManager " PACKAGE_VERSION " Settings Specification</title>\n"
+		"  <title>Configuration Settings</title>\n"
 		"  <para>\n");
 
 	for (fptr = funcs; fptr && *fptr; fptr++)

docs/api/network-manager-docs.xml

@@ -55,28 +55,61 @@
     </legalnotice>
   </bookinfo>
 
-  <reference id="ref-dbus">
+  <chapter id="ref-dbus">
     <title>D-Bus API Reference</title>
-    <partintro>
+    <para>
-      <para>
+      This part documents the D-Bus interface used to access the
-	This part documents the D-Bus interface used to access the
+      NetworkManager daemon.
-	NetworkManager daemon.
+    </para>
-      </para>
-    </partintro>
     <ulink url="spec.html"/>
-  </reference>
+  </chapter>
 
-  <reference id="ref-settings">
+  <chapter id="ref-settings">
     <title>Network Configuration Setting Specification</title>
-    <partintro>
+    <para>
-      <para>
+      This part documents the properties and value types of each "Setting"
-	This part documents the properties and value types of each "Setting"
+      object that composes the basic unit of NetworkManager configuration,
-	object that composes the basic unit of NetworkManager configuration,
+      the "Connection".  Each Connection object is simply a dictionare mapping
-	the "Connection".
+      setting names (like "wimax" or "bluetooth") to a dictionary of
-      </para>
+      key/value pairs that represents each itself.
-    </partintro>
+    </para>
     <xi:include href="settings-spec.xml" />
-  </reference>
+    <section id="secrets-flags">
+      <title>Secret flag types</title>
+      <para>
+        Each secret property in a setting has an associated "flags" property
+        that describes how to handle that secret.  The "flags" property is a
+        bitfield that contains zero or more of the following values logically
+        OR-ed together.
+      </para>
+      <para>
+        <itemizedlist>
+          <listitem>
+            <literal>0x0 (none)</literal> - the system is responsible for providing
+            and storing this secret.
+          </listitem>
+          <listitem>
+            <literal>0x1 (agent-owned)</literal> - a user-session secret agent
+            is responsible for providing and storing this secret; when it is
+            required, agents will be asked to provide it.
+          </listitem>
+          <listitem>
+            <literal>0x2 (not-saved)</literal> - this secret should not be saved
+            but should be requested from the user each time it is required. This
+            flag should be used for One-Time-Pad secrets, PIN codes from
+            hardware tokens, or if the user simply does not want to save the
+            secret.
+          </listitem>
+          <listitem>
+            <literal>0x4 (not-required)</literal> - in some situations it cannot
+            be automatically determined that a secret is required or not.  This
+            flag hints that the secret is not required and should not be
+            requested from the user.
+          </listitem>
+        </itemizedlist>
+      </para>
+    </section>
+  </chapter>
 
   <index>
     <title>Index</title>