Libguestfs - Feb 2016 - [PATCH] doc: add info on per-function needed feature

Document which feature, if any, is needed for a function; this should
help users in properly checking feature availability when using certain
functions.
---
 generator/c.ml       |  6 ++++++
 generator/fish.ml    | 10 +++++++++-
 generator/gobject.ml |  8 ++++++++
 generator/java.ml    |  7 +++++++
 generator/ocaml.ml   |  7 +++++++
 generator/perl.ml    |  6 ++++++
 generator/python.ml  |  5 +++++
 generator/ruby.ml    |  5 +++++
 8 files changed, 53 insertions(+), 1 deletion(-)

diff --git a/generator/c.ml b/generator/c.ml
index 7446412..9643a96 100644
--- a/generator/c.ml
+++ b/generator/c.ml
@@ -303,6 +303,12 @@ I<The caller must free the returned buffer after
use>.\n\n"
     pr "This function takes a key or passphrase parameter which
 could contain sensitive material.  Read the section
 L</KEYS AND PASSPHRASES> for more information.\n\n";
+  (match f.optional with
+  | None -> ()
+  | Some opt ->
+    pr "This function depends on the feature C<%s>.  See also
+L</guestfs_feature_available>.\n\n" opt
+  );
   (match version_added f with
   | Some version -> pr "(Added in %s)\n\n" version
   | None -> assert false
diff --git a/generator/fish.ml b/generator/fish.ml
index 0cbc781..864f65d 100644
--- a/generator/fish.ml
+++ b/generator/fish.ml
@@ -897,9 +897,17 @@ Guestfish will prompt for these separately.\n\n";
       if f.protocol_limit_warning then
         pr "%s\n\n" protocol_limit_warning;
 
-      match deprecation_notice ~replace_underscores:true f with
+      (match deprecation_notice ~replace_underscores:true f with
       | None -> ()
       | Some txt -> pr "%s\n\n" txt
+      );
+
+      (match f.optional with
+      | None -> ()
+      | Some opt ->
+        pr "This command depends on the feature C<%s>.   See also
+L</feature-available>.\n\n" opt
+      );
   ) fishdoc_functions_sorted
 
 (* Generate documentation for guestfish-only commands. *)
diff --git a/generator/gobject.ml b/generator/gobject.ml
index 60c053c..b89463e 100644
--- a/generator/gobject.ml
+++ b/generator/gobject.ml
@@ -1081,6 +1081,14 @@ guestfs_session_close (GuestfsSession *session, GError
**err)
       pr " *\n";
       pr " * %s\n" doc;
 
+      (match f.optional with
+      | None -> ()
+      | Some opt ->
+        pr " * This function depends on the feature
\"%s\".\n" opt;
+        pr " * See also guestfs_session_feature_available().\n";
+        pr " *\n";
+      );
+
       pr " * Returns: ";
       (match ret with
       | RErr ->
diff --git a/generator/java.ml b/generator/java.ml
index f303048..4821b34 100644
--- a/generator/java.ml
+++ b/generator/java.ml
@@ -274,6 +274,13 @@ public class GuestFS {
         pr "   * %s\n" f.shortdesc;
         pr "   * </p><p>\n";
         pr "   * %s\n" doc;
+        (match f.optional with
+        | None -> ()
+        | Some opt ->
+          pr "   * </p><p>\n";
+          pr "   * This function depends on the feature \"%s\". 
See also {@link #feature_available}.\n"
+            opt;
+        );
         pr "   * </p>\n";
         (match version_added f with
         | None -> ()
diff --git a/generator/ocaml.ml b/generator/ocaml.ml
index 288e91f..ef04540 100644
--- a/generator/ocaml.ml
+++ b/generator/ocaml.ml
@@ -177,6 +177,13 @@ end
       else
         pr "%s(** alias for {!%s}" indent f.name;
 
+      (match f.optional with
+      | None -> ()
+      | Some opt ->
+          has_tags := true;
+          pr "\n\n    This function depends on the feature
\"%s\".  See also {!feature_available}."
+            opt
+      );
       (match f.deprecated_by with
        | None -> ()
        | Some replacement ->
diff --git a/generator/perl.ml b/generator/perl.ml
index f11477b..19cabb6 100644
--- a/generator/perl.ml
+++ b/generator/perl.ml
@@ -895,6 +895,12 @@ errnos:
       pr "%s\n\n" longdesc;
       if f.protocol_limit_warning then
         pr "%s\n\n" protocol_limit_warning;
+      (match f.optional with
+      | None -> ()
+      | Some opt ->
+        pr "This function depends on the feature C<%s>.  See also
+C<$g-E<gt>feature-available>.\n\n" opt
+      );
       (match deprecation_notice f with
       | None -> ()
       | Some txt -> pr "%s\n\n" txt
diff --git a/generator/python.ml b/generator/python.ml
index c618bf0..9663fb4 100644
--- a/generator/python.ml
+++ b/generator/python.ml
@@ -817,6 +817,11 @@ class GuestFS(object):
           match deprecation_notice f with
           | None -> doc
           | Some txt -> doc ^ "\n\n" ^ txt in
+        let doc +          match f.optional with
+          | None -> doc
+          | Some opt ->
+            doc ^ sprintf "\n\nThis function depends on the feature
C<%s>.  See also C<g.feature-available>." opt in
         let doc = pod2text ~width:60 f.name doc in
         let doc = List.map (fun line -> replace_str line "\\"
"\\\\") doc in
         let doc = String.concat "\n        " doc in
diff --git a/generator/ruby.ml b/generator/ruby.ml
index 9567925..97ccfdc 100644
--- a/generator/ruby.ml
+++ b/generator/ruby.ml
@@ -481,6 +481,11 @@ get_all_event_callbacks (guestfs_h *g, size_t *len_rtn)
           | { deprecated_by = None } -> doc
           | { deprecated_by = Some alt } ->
             doc ^ (sprintf "\n *\n * [Deprecated] In new code, use
rdoc-ref:%s instead." alt) in
+        let doc +          match f.optional with
+          | None -> doc
+          | Some opt ->
+            doc ^ sprintf "\n *\n * [Feature] This function depends on the
feature +%s+.  See also {#feature_available}[rdoc-ref:feature_available]."
opt in
 
         (* Because Ruby documentation appears as C comments, we must
          * replace any instance of "/*".
-- 
2.5.0

They are converted as additional empty paragraphs but adding nothing to
the generated API documentation.  Also avoids warnings about them by
javadoc.
---
 generator/java.ml | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/generator/java.ml b/generator/java.ml
index 4821b34..2a41a5f 100644
--- a/generator/java.ml
+++ b/generator/java.ml
@@ -32,6 +32,13 @@ open C
 
 let generate_header = generate_header ~inputs:["generator/java.ml"]
 
+let drop_empty_trailing_lines l +  let rec loop = function
+    | "" :: tl -> loop tl
+    | x -> x
+  in
+  List.rev (loop (List.rev l))
+
 (* Generate Java bindings GuestFS.java file. *)
 let rec generate_java_java ()    generate_header CStyle LGPLv2plus;
@@ -262,6 +269,7 @@ public class GuestFS {
             doc ^ "\n\n" ^ protocol_limit_warning
           else doc in
         let doc = pod2text ~width:60 f.name doc in
+        let doc = drop_empty_trailing_lines doc in
         let doc = List.map (		(* RHBZ#501883 *)
           function
           | "" -> "</p><p>"
-- 
2.5.0