libnm/docs: fix documentation for "proxy.pac-script"

src/libnm-core-impl/nm-setting-proxy.c

@@ -114,7 +114,7 @@ nm_setting_proxy_get_pac_url(NMSettingProxy *setting)
  * nm_setting_proxy_get_pac_script:
  * @setting: the #NMSettingProxy
  *
- * Returns: the PAC script
+ * Returns: the PAC script.
  *
  * Since: 1.6
  **/
@@ -315,15 +315,25 @@ nm_setting_proxy_class_init(NMSettingProxyClass *klass)
     /**
      * NMSettingProxy:pac-script:
      *
-     * PAC script for the connection.
+     * PAC script for the connection. This is an UTF-8 encoded javascript code
+     * that defines a FindProxyForURL() function.
      *
      * Since: 1.6
      **/
+    /* ---nmcli---
+     * property: pac-script
+     * description: The PAC script. In the profile this must be an UTF-8 encoded javascript code that defines
+     *   a FindProxyForURL() function.
+     *   When setting the property in nmcli, a filename is accepted too. In that case,
+     *   nmcli will read the content of the file and set the script. The prefixes "file://" and "js://" are
+     *   supported to explicitly differentiate between the two.
+     * ---end---
+     */
     /* ---ifcfg-rh---
      * property: pac-script
      * variable: PAC_SCRIPT(+)
-     * description: Path of the PAC script.
-     * example: PAC_SCRIPT=/home/joe/proxy.pac
+     * description: The PAC script. This is an UTF-8 encoded javascript code that defines a FindProxyForURL() function.
+     * example: PAC_SCRIPT="function FindProxyForURL (url, host) { return 'PROXY proxy.example.com:8080; DIRECT'; }"
      * ---end---
      */
     _nm_setting_property_define_direct_string(properties_override,

src/libnmc-setting/settings-docs.h.in

@@ -340,7 +340,7 @@
 #define DESCRIBE_DOC_NM_SETTING_PPPOE_USERNAME N_("Username used to authenticate with the PPPoE service.")
 #define DESCRIBE_DOC_NM_SETTING_PROXY_BROWSER_ONLY N_("Whether the proxy configuration is for browser only.")
 #define DESCRIBE_DOC_NM_SETTING_PROXY_METHOD N_("Method for proxy configuration, Default is NM_SETTING_PROXY_METHOD_NONE (0)")
-#define DESCRIBE_DOC_NM_SETTING_PROXY_PAC_SCRIPT N_("PAC script for the connection.")
+#define DESCRIBE_DOC_NM_SETTING_PROXY_PAC_SCRIPT N_("The PAC script. In the profile this must be an UTF-8 encoded javascript code that defines a FindProxyForURL() function. When setting the property in nmcli, a filename is accepted too. In that case, nmcli will read the content of the file and set the script. The prefixes \"file://\" and \"js://\" are supported to explicitly differentiate between the two.")
 #define DESCRIBE_DOC_NM_SETTING_PROXY_PAC_URL N_("PAC URL for obtaining PAC file.")
 #define DESCRIBE_DOC_NM_SETTING_SERIAL_BAUD N_("Speed to use for communication over the serial port.  Note that this value usually has no effect for mobile broadband modems as they generally ignore speed settings and use the highest available speed.")
 #define DESCRIBE_DOC_NM_SETTING_SERIAL_BITS N_("Byte-width of the serial communication. The 8 in \"8n1\" for example.")

src/nmcli/generate-docs-nm-settings-nmcli.xml.in

@@ -911,7 +911,7 @@
                   description="PAC URL for obtaining PAC file." />
         <property name="pac-script"
                   alias="pac-script"
-                  description="PAC script for the connection." />
+                  description="The PAC script. In the profile this must be an UTF-8 encoded javascript code that defines a FindProxyForURL() function. When setting the property in nmcli, a filename is accepted too. In that case, nmcli will read the content of the file and set the script. The prefixes &quot;file://&quot; and &quot;js://&quot; are supported to explicitly differentiate between the two." />
     </setting>
     <setting name="serial" >
         <property name="baud"

tools/generate-docs-nm-settings-docs-gir.py

@@ -149,7 +149,13 @@ def get_docs(propxml):
     doc = re.sub(r"#([A-Z]\w*)", r"\1", doc)
 
     # Remove sentences that refer to functions
-    doc = re.sub(r"\.\s+[^.]*\w\(\)[^.]*\.", r".", doc)
+    if "FindProxyForURL()" in doc:
+        # FIXME: this would break the description for "proxy.pac-script"
+        # Work around. But really the entire approach here is flawed
+        # and needs improvement.
+        pass
+    else:
+        doc = re.sub(r"\.\s+[^.]*\w\(\)[^.]*\.", r".", doc)
 
     return doc