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