generator: Add visibility to action struct

The visibility field in action replaces in_fish, in_docs and internal. The defined types are: VPublic: A public API. This is exported and documented in all language bindings, and in guestfish. VStateTest: A public API which queries the library state machine. It is exported and documented in all language bindings, but not guestfish. VBindTest: An internal API used only for testing language bindings. It is guarded by GUESTFS_PRIVATE in the C api, but exported by all other language bindings as it is required for testing. If language bindings offer any way to guard use of these apis, that mechanism should be used. It is not documented anywhere. VDebug: A debugging API. It is exported by all language bindings, and in guestfish, but is not documented anywhere. VInternal: An internal-only API. It is guarded by GUESTFS_PRIVATE in the C api, and not exported at all in any other language binding. It is not documented anywhere.
2026-03-21 22:53:37 +00:00 · 2013-02-04 14:11:57 +00:00
parent f9bafde5e7
commit ca056d53bd
17 changed files with 218 additions and 163 deletions
--- a/generator/actions.ml
+++ b/generator/actions.ml
@@ -27,8 +27,8 @@ open Utils
 let defaults = { name = ""; style = RErr, [], []; proc_nr = None;
                 tests = []; shortdesc = ""; longdesc = "";
                 protocol_limit_warning = false; fish_alias = [];
-                 fish_output = None; in_fish = true; in_docs = true;
-                 internal = false; deprecated_by = None; optional = None;
+                 fish_output = None; visibility = VPublic;
+                 deprecated_by = None; optional = None;
                 progress = false; camel_name = "";
                 cancellable = false; config_only = false;
                 once_had_no_optargs = false; blocking = true;
@@ -76,7 +76,7 @@ let test_functions = [
  { defaults with
    name = "internal_test";
    style = RErr, test_all_args, test_all_optargs;
-    in_fish = false; in_docs = false; internal = true; cancellable = true;
+    visibility = VBindTest; cancellable = true;
    blocking = false;
    shortdesc = "internal test function - do not use";
    longdesc = "\
@@ -92,7 +92,7 @@ You probably don't want to call this function." };
  { defaults with
    name = "internal_test_only_optargs";
    style = RErr, [], [OInt "test"];
-    in_fish = false; in_docs = false; internal = true; cancellable = true;
+    visibility = VBindTest; cancellable = true;
    blocking = false;
    shortdesc = "internal test function - do not use";
    longdesc = "\
@@ -108,7 +108,7 @@ You probably don't want to call this function." };
  { defaults with
    name = "internal_test_63_optargs";
    style = RErr, [], [OInt "opt1"; OInt "opt2"; OInt "opt3"; OInt "opt4"; OInt "opt5"; OInt "opt6"; OInt "opt7"; OInt "opt8"; OInt "opt9"; OInt "opt10"; OInt "opt11"; OInt "opt12"; OInt "opt13"; OInt "opt14"; OInt "opt15"; OInt "opt16"; OInt "opt17"; OInt "opt18"; OInt "opt19"; OInt "opt20"; OInt "opt21"; OInt "opt22"; OInt "opt23"; OInt "opt24"; OInt "opt25"; OInt "opt26"; OInt "opt27"; OInt "opt28"; OInt "opt29"; OInt "opt30"; OInt "opt31"; OInt "opt32"; OInt "opt33"; OInt "opt34"; OInt "opt35"; OInt "opt36"; OInt "opt37"; OInt "opt38"; OInt "opt39"; OInt "opt40"; OInt "opt41"; OInt "opt42"; OInt "opt43"; OInt "opt44"; OInt "opt45"; OInt "opt46"; OInt "opt47"; OInt "opt48"; OInt "opt49"; OInt "opt50"; OInt "opt51"; OInt "opt52"; OInt "opt53"; OInt "opt54"; OInt "opt55"; OInt "opt56"; OInt "opt57"; OInt "opt58"; OInt "opt59"; OInt "opt60"; OInt "opt61"; OInt "opt62"; OInt "opt63"];
-    in_fish = false; in_docs = false; internal = true; cancellable = true;
+    visibility = VBindTest; cancellable = true;
    blocking = false;
    shortdesc = "internal test function - do not use";
    longdesc = "\
@@ -128,7 +128,7 @@ You probably don't want to call this function." }
      { defaults with
        name = name;
        style = ret, [String "val"], [];
-        in_fish = false; in_docs = false; internal = true;
+        visibility = VBindTest;
        blocking = false;
        shortdesc = "internal test function - do not use";
        longdesc = "\
@@ -142,7 +142,7 @@ You probably don't want to call this function." };
      { defaults with
        name = name ^ "err";
        style = ret, [], [];
-        in_fish = false; in_docs = false; internal = true;
+        visibility = VBindTest;
        blocking = false;
        shortdesc = "internal test function - do not use";
        longdesc = "\
@@ -166,7 +166,7 @@ let non_daemon_functions = test_functions @ [
  { defaults with
    name = "internal_test_set_output";
    style = RErr, [String "filename"], [];
-    in_fish = false; in_docs = false; internal = true;
+    visibility = VBindTest;
    blocking = false;
    shortdesc = "internal test function - do not use";
    longdesc = "\
@@ -181,7 +181,7 @@ You probably don't want to call this function." };
  { defaults with
    name = "internal_test_close_output";
    style = RErr, [], [];
-    in_fish = false; in_docs = false; internal = true;
+    visibility = VBindTest;
    blocking = false;
    shortdesc = "internal test function - do not use";
    longdesc = "\
@@ -214,7 +214,8 @@ very cheap to create, so create a new one for each launch." };
  { defaults with
    name = "wait_ready";
    style = RErr, [], [];
-    in_fish = false; deprecated_by = Some "launch";
+    visibility = VStateTest;
+    deprecated_by = Some "launch";
    blocking = false;
    shortdesc = "wait until the qemu subprocess launches (no op)";
    longdesc = "\
@@ -434,6 +435,7 @@ This returns the verbose messages flag." };
  { defaults with
    name = "is_ready";
    style = RBool "ready", [], [];
+    visibility = VStateTest;
    blocking = false;
    tests = [
      InitNone, Always, TestOutputTrue (
@@ -464,6 +466,7 @@ For more information on states, see L<guestfs(3)>." };
  { defaults with
    name = "is_launching";
    style = RBool "launching", [], [];
+    visibility = VStateTest;
    blocking = false;
    tests = [
      InitNone, Always, TestOutputFalse (
@@ -479,7 +482,7 @@ For more information on states, see L<guestfs(3)>." };
  { defaults with
    name = "is_busy";
    style = RBool "busy", [], [];
-    in_docs = false;
+    visibility = VStateTest;
    blocking = false;
    tests = [
      InitNone, Always, TestOutputFalse (
@@ -487,13 +490,15 @@ For more information on states, see L<guestfs(3)>." };
    ];
    shortdesc = "is busy processing a command";
    longdesc = "\
-This always returns false.  Do not use this function.
+This always returns false.  This function is deprecated with no
+replacement.  Do not use this function.

 For more information on states, see L<guestfs(3)>." };

  { defaults with
    name = "get_state";
    style = RInt "state", [], [];
+    visibility = VStateTest;
    blocking = false;
    shortdesc = "get the current state";
    longdesc = "\
@@ -1344,7 +1349,7 @@ Please read L<guestfs(3)/INSPECTION> for more details." };
  { defaults with
    name = "debug_drives";
    style = RStringList "cmdline", [], [];
-    in_docs = false;
+    visibility = VDebug;
    blocking = false;
    shortdesc = "debug the drives (internal use only)";
    longdesc = "\
@@ -4232,7 +4237,7 @@ as for the L<mount(8)> I<-o> and I<-t> flags." };
    name = "debug";
    style = RString "result", [String "subcmd"; StringList "extraargs"], [];
    proc_nr = Some 76;
-    in_docs = false;
+    visibility = VDebug;
    shortdesc = "debugging and internals";
    longdesc = "\
 The C<guestfs_debug> command exposes some internals of
@@ -6826,7 +6831,7 @@ yourself (Augeas support makes this relatively easy)." };
    name = "internal_lstatlist";
    style = RStructList ("statbufs", "stat"), [Pathname "path"; StringList "names"], [];
    proc_nr = Some 204;
-    in_docs = false; in_fish = false; internal = true;
+    visibility = VInternal;
    shortdesc = "lstat on multiple files";
    longdesc = "\
 This call allows you to perform the C<guestfs_lstat> operation
@@ -6850,7 +6855,7 @@ into smaller groups of names." };
    name = "internal_lxattrlist";
    style = RStructList ("xattrs", "xattr"), [Pathname "path"; StringList "names"], [];
    proc_nr = Some 205;
-    in_docs = false; in_fish = false; internal = true;
+    visibility = VInternal;
    optional = Some "linuxxattrs";
    shortdesc = "lgetxattr on multiple files";
    longdesc = "\
@@ -6880,7 +6885,7 @@ into smaller groups of names." };
    name = "internal_readlinklist";
    style = RStringList "links", [Pathname "path"; StringList "names"], [];
    proc_nr = Some 206;
-    in_docs = false; in_fish = false; internal = true;
+    visibility = VInternal;
    shortdesc = "readlink on multiple files";
    longdesc = "\
 This call allows you to do a C<readlink> operation
@@ -7603,7 +7608,8 @@ unless it has been set by calling C<guestfs_umask>." };
    name = "debug_upload";
    style = RErr, [FileIn "filename"; String "tmpname"; Int "mode"], [];
    proc_nr = Some 241;
-    in_docs = false; cancellable = true;
+    visibility = VDebug;
+    cancellable = true;
    shortdesc = "upload a file to the appliance (internal use only)";
    longdesc = "\
 The C<guestfs_debug_upload> command uploads a file to
@@ -7678,7 +7684,7 @@ to ensure the length of the file is exactly C<len> bytes." };
    name = "internal_write";
    style = RErr, [Pathname "path"; BufferIn "content"], [];
    proc_nr = Some 246;
-    in_fish = false; in_docs = false; internal = true;
+    visibility = VInternal;
    protocol_limit_warning = true;
    tests = [
      InitScratchFS, Always, TestOutput (
@@ -8394,7 +8400,7 @@ See also L<guestfs(3)/RESIZE2FS ERRORS>." };
    name = "internal_autosync";
    style = RErr, [], [];
    proc_nr = Some 282;
-    in_fish = false; in_docs = false; internal = true;
+    visibility = VInternal;
    shortdesc = "internal autosync operation";
    longdesc = "\
 This command performs the autosync operation just before the
@@ -8540,7 +8546,7 @@ See also L<btrfs(8)>." };
    name = "internal_write_append";
    style = RErr, [Pathname "path"; BufferIn "content"], [];
    proc_nr = Some 290;
-    in_fish = false; in_docs = false; internal = true;
+    visibility = VInternal;
    protocol_limit_warning = true;
    tests = [
      InitScratchFS, Always, TestOutput (
@@ -10302,7 +10308,7 @@ are the full raw block device and partition names
    name = "internal_hot_add_drive";
    style = RErr, [String "label"], [];
    proc_nr = Some 370;
-    in_fish = false; in_docs = false; internal = true;
+    visibility = VInternal;
    tests = [];
    shortdesc = "internal hotplugging operation";
    longdesc = "\
@@ -10312,7 +10318,7 @@ This function is used internally when hotplugging drives." };
    name = "internal_hot_remove_drive_precheck";
    style = RErr, [String "label"], [];
    proc_nr = Some 371;
-    in_fish = false; in_docs = false; internal = true;
+    visibility = VInternal;
    tests = [];
    shortdesc = "internal hotplugging operation";
    longdesc = "\
@@ -10322,7 +10328,7 @@ This function is used internally when hotplugging drives." };
    name = "internal_hot_remove_drive";
    style = RErr, [String "label"], [];
    proc_nr = Some 372;
-    in_fish = false; in_docs = false; internal = true;
+    visibility = VInternal;
    tests = [];
    shortdesc = "internal hotplugging operation";
    longdesc = "\
@@ -11054,11 +11060,31 @@ let non_daemon_functions, daemon_functions =
 (* All functions. *)
 let all_functions = non_daemon_functions @ daemon_functions

+let is_external { visibility = v } = match v with
+  | VPublic | VStateTest | VBindTest | VDebug -> true
+  | VInternal -> false
+
+let is_internal f = not (is_external f)
+
+let is_documented { visibility = v } = match v with
+  | VPublic | VStateTest -> true
+  | VBindTest | VDebug | VInternal -> false
+
+let is_fish { visibility = v } = match v with
+  | VPublic | VDebug -> true
+  | VStateTest | VBindTest | VInternal -> false
+
 let external_functions =
-  List.filter (fun x -> not x.internal) all_functions
+  List.filter is_external all_functions

 let internal_functions =
-  List.filter (fun x -> x.internal) all_functions
+  List.filter is_internal all_functions
+
+let documented_functions =
+  List.filter is_documented all_functions
+
+let fish_functions =
+  List.filter is_fish all_functions

 (* In some places we want the functions to be displayed sorted
 * alphabetically, so this is useful:
@@ -11071,6 +11097,12 @@ let external_functions_sorted =
 let internal_functions_sorted =
  List.sort action_compare internal_functions

+let documented_functions_sorted =
+  List.sort action_compare documented_functions
+
+let fish_functions_sorted =
+  List.sort action_compare fish_functions
+
 (* This is used to generate the src/MAX_PROC_NR file which
 * contains the maximum procedure number, a surrogate for the
 * ABI version number.  See src/Makefile.am for the details.
--- a/generator/actions.mli
+++ b/generator/actions.mli
@@ -29,12 +29,30 @@ val daemon_functions : Types.action list
 val all_functions : Types.action list
 (** Concatenation of [non_daemon_functions] and [daemon_functions] lists. *)

+val is_external : Types.action -> bool
+(** Returns true if function is external, false otherwise *)
+
+val is_internal : Types.action -> bool
+(** Returns true if function is internal, false otherwise *)
+
+val is_documented : Types.action -> bool
+(** Returns true if function should be documented, false otherwise *)
+
+val is_fish : Types.action -> bool
+(** Returns true if function should be in guestfish, false otherwise *)
+
 val external_functions : Types.action list
 (** [all_functions] filtered for external functions **)

 val internal_functions : Types.action list
 (** [all_functions] filtered for internal functions **)

+val documented_functions : Types.action list
+(** [all_functions] filtered for functions requiring documentation **)
+
+val fish_functions : Types.action list
+(** [all_functions] filtered for functions in guestfish **)
+
 val all_functions_sorted : Types.action list
 (** [all_functions] but sorted by name. *)

@@ -44,6 +62,12 @@ val external_functions_sorted : Types.action list
 val internal_functions_sorted : Types.action list
 (** [internal_functions] but sorted by name. *)

+val documented_functions_sorted : Types.action list
+(** [documented_functions] but sorted by name. *)
+
+val fish_functions_sorted : Types.action list
+(** [fish_functions] but sorted by name. *)
+
 val test_functions : Types.action list
 (** Internal test functions used to test the language bindings. *)

--- a/generator/c.ml
+++ b/generator/c.ml
@@ -44,6 +44,18 @@ let hash_matches h { name = name } =

 type optarg_proto = Dots | VA | Argv

+let is_public { visibility = v } = match v with
+  | VPublic | VStateTest | VDebug -> true
+  | VBindTest | VInternal -> false
+
+let is_private f = not (is_public f)
+
+let public_functions_sorted =
+  List.filter is_public all_functions_sorted
+
+let private_functions_sorted =
+  List.filter is_private all_functions_sorted
+
 (* Generate a C function prototype. *)
 let rec generate_prototype ?(extern = true) ?(static = false)
    ?(semicolon = true)
@@ -186,13 +198,12 @@ and generate_c_call_args ?handle ?(implicit_size_ptr = "&size")
 and generate_actions_pod () =
  List.iter (
    function
-    | { in_docs = false } -> ()
-    | ({ in_docs = true; once_had_no_optargs = false } as f) ->
+    | ({ once_had_no_optargs = false } as f) ->
      generate_actions_pod_entry f
-    | ({ in_docs = true; once_had_no_optargs = true } as f) ->
+    | ({ once_had_no_optargs = true } as f) ->
      generate_actions_pod_back_compat_entry f;
      generate_actions_pod_entry f
-  ) all_functions_sorted
+  ) documented_functions_sorted

 and generate_actions_pod_entry ({ c_name = c_name;
                                  style = ret, args, optargs as style } as f) =
@@ -679,7 +690,7 @@ extern GUESTFS_DLL_PUBLIC void *guestfs_next_private (guestfs_h *g, const char *
        generate_action_header f
  ) in

-  generate_all_headers external_functions_sorted;
+  generate_all_headers public_functions_sorted;

  pr "\
 #if GUESTFS_PRIVATE
@@ -694,7 +705,7 @@ extern GUESTFS_DLL_PUBLIC int guestfs___for_each_disk (guestfs_h *g, /* virDomai

 ";

-  generate_all_headers internal_functions_sorted;
+  generate_all_headers private_functions_sorted;

  pr "\
 /* Private structures. */
@@ -711,7 +722,7 @@ pr "\
  List.iter (
    fun { name = shortname } ->
      pr "#define LIBGUESTFS_HAVE_%s 1\n" (String.uppercase shortname);
-  ) internal_functions_sorted;
+  ) private_functions_sorted;

 pr "\

@@ -738,7 +749,7 @@ pr "\
  List.iter (
    fun { name = shortname } ->
      pr "#define LIBGUESTFS_HAVE_%s 1\n" (String.uppercase shortname);
-  ) external_functions_sorted;
+  ) public_functions_sorted;

  pr "
 /* End of deprecated macros. */
--- a/generator/csharp.ml
+++ b/generator/csharp.ml
@@ -131,7 +131,7 @@ namespace Guestfs
      ) cols;
      pr "    }\n";
      pr "\n"
-  ) structs;
+  ) external_structs;

  (* Generate C# function bindings. *)
  List.iter (
@@ -282,7 +282,7 @@ namespace Guestfs
      pr "\n";

      List.iter generate_alias non_c_aliases
-  ) all_functions_sorted;
+  ) external_functions_sorted;

  pr "  }
 }
--- a/generator/erlang.ml
+++ b/generator/erlang.ml
@@ -50,7 +50,7 @@ let rec generate_erlang_erl () =
      in
      export name;
      List.iter export aliases
-  ) all_functions_sorted;
+  ) external_functions_sorted;

  pr "\n";

@@ -178,7 +178,7 @@ loop(Port) ->
      ) aliases;

      pr "\n"
-  ) all_functions_sorted
+  ) external_functions_sorted

 and generate_erlang_c () =
  generate_header CStyle GPLv2plus;
@@ -279,7 +279,7 @@ extern void free_strings (char **r);
        (* generate the function for typ *)
        emit_copy_list_function typ
    | typ, _ -> () (* empty *)
-  ) (rstructs_used_by all_functions);
+  ) (rstructs_used_by external_functions);

  (* The wrapper functions. *)
  List.iter (
@@ -460,7 +460,7 @@ extern void free_strings (char **r);

      pr "}\n";
      pr "\n";
-  ) all_functions_sorted;
+  ) external_functions_sorted;

  pr "\

@@ -479,7 +479,7 @@ dispatch (ETERM *message)
      pr "if (atom_equals (fun, \"%s\"))\n" name;
      pr "    return run_%s (message);\n" name;
      pr "  else ";
-  ) all_functions_sorted;
+  ) external_functions_sorted;

  pr "return unknown_function (fun);
 }
--- a/generator/fish.ml
+++ b/generator/fish.ml
@@ -31,6 +31,9 @@ open Prepopts
 open C
 open Events

+let fish_functions_and_commands_sorted =
+  List.sort action_compare (fish_functions_sorted @ fish_commands)
+
 let doc_opttype_of = function
  | OBool n -> "true|false"
  | OInt n
@@ -47,13 +50,6 @@ let get_aliases { fish_alias = fish_alias; non_c_aliases = non_c_aliases } =
 let generate_fish_cmds () =
  generate_header CStyle GPLv2plus;

-  let all_functions =
-    List.filter (fun { in_fish = b } -> b) all_functions in
-  let all_functions_sorted =
-    List.filter (fun { in_fish = b } -> b) all_functions_sorted in
-
-  let all_functions_and_fish_commands_sorted =
-    List.sort action_compare (all_functions_sorted @ fish_commands) in

  pr "#include <config.h>\n";
  pr "\n";
@@ -84,7 +80,7 @@ let generate_fish_cmds () =
    fun { name = name } ->
      pr "static int run_%s (const char *cmd, size_t argc, char *argv[]);\n"
        name
-  ) all_functions;
+  ) fish_functions;

  pr "\n";

@@ -174,7 +170,7 @@ Guestfish will prompt for these separately."
      pr "  .run = run_%s\n" name;
      pr "};\n";
      pr "\n";
-  ) all_functions;
+  ) fish_functions;

  (* list_commands function, which implements guestfish -h *)
  pr "void\n";
@@ -187,7 +183,7 @@ Guestfish will prompt for these separately."
      let name = replace_char name '_' '-' in
      pr "  printf (\"%%-20s %%s\\n\", \"%s\", _(\"%s\"));\n"
        name shortdesc
-  ) all_functions_and_fish_commands_sorted;
+  ) fish_functions_and_commands_sorted;
  pr "  printf (\"    %%s\\n\",";
  pr "          _(\"Use -h <cmd> / help <cmd> to show detailed help for a command.\"));\n";
  pr "}\n";
@@ -288,7 +284,7 @@ Guestfish will prompt for these separately."
        (* generate the function for typ *)
        emit_print_list_function typ
    | typ, _ -> () (* empty *)
-  ) (rstructs_used_by all_functions);
+  ) (rstructs_used_by fish_functions);

  (* Emit a print_TYPE function definition only if that function is used. *)
  List.iter (
@@ -301,7 +297,7 @@ Guestfish will prompt for these separately."
        pr "}\n";
        pr "\n";
    | typ, _ -> () (* empty *)
-  ) (rstructs_used_by all_functions);
+  ) (rstructs_used_by fish_functions);

  (* run_<action> actions *)
  List.iter (
@@ -647,7 +643,7 @@ Guestfish will prompt for these separately."
      pr "  return ret;\n";
      pr "}\n";
      pr "\n"
-  ) all_functions;
+  ) fish_functions;

  (* run_action function *)
  pr "int\n";
@@ -686,12 +682,6 @@ and generate_fish_cmds_h () =
 and generate_fish_cmds_gperf () =
  generate_header CStyle GPLv2plus;

-  let all_functions_sorted =
-    List.filter (fun { in_fish = b } -> b) all_functions_sorted in
-
-  let all_functions_and_fish_commands_sorted =
-    List.sort action_compare (all_functions_sorted @ fish_commands) in
-
  pr "\
 %%language=ANSI-C
 %%define lookup-function-name lookup_fish_command
@@ -713,7 +703,7 @@ and generate_fish_cmds_gperf () =
  List.iter (
    fun { name = name } ->
      pr "extern struct command_entry %s_cmd_entry;\n" name
-  ) all_functions_and_fish_commands_sorted;
+  ) fish_functions_and_commands_sorted;

  pr "\
 %%}
@@ -740,15 +730,12 @@ struct command_table;
        fun alias ->
          pr "%s, &%s_cmd_entry\n" alias name;
      ) aliases;
-  ) all_functions_and_fish_commands_sorted
+  ) fish_functions_and_commands_sorted

 (* Readline completion for guestfish. *)
 and generate_fish_completion () =
  generate_header CStyle GPLv2plus;

-  let all_functions =
-    List.filter (fun { in_fish = b } -> b) all_functions in
-
  pr "\
 #include <config.h>

@@ -777,7 +764,7 @@ static const char *const commands[] = {
        let aliases = get_aliases f in
        let name2 = replace_char name '_' '-' in
        name2 :: aliases
-    ) (all_functions @ fish_commands) in
+    ) (fish_functions_and_commands_sorted) in
  let commands = List.flatten commands in

  List.iter (pr "  \"%s\",\n") commands;
@@ -837,10 +824,9 @@ do_completion (const char *text, int start, int end)

 (* Generate the POD documentation for guestfish. *)
 and generate_fish_actions_pod () =
-  let all_functions_sorted =
-    List.filter (
-      fun { in_fish = in_fish; in_docs = in_docs } -> in_fish && in_docs
-    ) all_functions_sorted in
+  let fishdoc_functions_sorted =
+    List.filter is_documented fish_functions_sorted
+  in

  let rex = Str.regexp "C<guestfs_\\([^>]+\\)>" in

@@ -902,7 +888,7 @@ Guestfish will prompt for these separately.\n\n";
      match deprecation_notice ~replace_underscores:true f with
      | None -> ()
      | Some txt -> pr "%s\n\n" txt
-  ) all_functions_sorted
+  ) fishdoc_functions_sorted

 (* Generate documentation for guestfish-only commands. *)
 and generate_fish_commands_pod () =
--- a/generator/gobject.ml
+++ b/generator/gobject.ml
@@ -115,7 +115,7 @@ let filenames =
      function
      | { style = _, _, (_::_) } -> true
      | { style = _, _, [] } -> false
-    ) all_functions
+    ) external_functions
  )

 let header_start filename =
@@ -697,7 +697,7 @@ gboolean guestfs_session_close(GuestfsSession *session, GError **err);
    fun ({ name = name; style = style } as f) ->
      generate_gobject_proto name style f;
      pr ";\n";
-  ) all_functions;
+  ) external_functions;

  header_end filename

@@ -1276,4 +1276,4 @@ guestfs_session_close(GuestfsSession *session, GError **err)
      );

      pr "}\n";
-  ) all_functions
+  ) external_functions
--- a/generator/haskell.ml
+++ b/generator/haskell.ml
@@ -60,7 +60,7 @@ module Guestfs (
  List.iter (
    fun { name = name; style = style } ->
      if can_generate style then pr ",\n  %s" name
-  ) all_functions;
+  ) external_functions;

  pr "
  ) where
@@ -205,7 +205,7 @@ assocListOfHashtable (a:b:rest) = (a,b) : assocListOfHashtable rest
        );
        pr "\n";
      )
-  ) all_functions
+  ) external_functions

 and generate_haskell_prototype ~handle ?(hs = false) (ret, args, optargs) =
  pr "%s -> " handle;
--- a/generator/java.ml
+++ b/generator/java.ml
@@ -246,11 +246,11 @@ public class GuestFS {

  (* Methods. *)
  List.iter (
-    fun ({ name = name; style = (ret, args, optargs as style);
-           in_docs = in_docs; shortdesc = shortdesc;
-           longdesc = longdesc; non_c_aliases = non_c_aliases } as f) ->
-      if in_docs then (
-        let doc = replace_str longdesc "C<guestfs_" "C<g." in
+    fun f ->
+      let ret, args, optargs = f.style in
+
+      if is_documented f then (
+        let doc = replace_str f.longdesc "C<guestfs_" "C<g." in
        let doc =
          if optargs <> [] then
            doc ^ "\n\nOptional arguments are supplied in the final Map<String,Object> parameter, which is a hash of the argument name to its value (cast to Object).  Pass an empty Map or null for no optional arguments."
@@ -263,7 +263,7 @@ public class GuestFS {
          match deprecation_notice f with
          | None -> doc
          | Some txt -> doc ^ "\n\n" ^ txt in
-        let doc = pod2text ~width:60 name doc in
+        let doc = pod2text ~width:60 f.name doc in
        let doc = List.map (		(* RHBZ#501883 *)
          function
          | "" -> "<p>"
@@ -272,19 +272,19 @@ public class GuestFS {
        let doc = String.concat "\n   * " doc in

        pr "  /**\n";
-        pr "   * %s\n" shortdesc;
+        pr "   * %s\n" f.shortdesc;
        pr "   * <p>\n";
        pr "   * %s\n" doc;
        pr "   * @throws LibGuestFSException\n";
        pr "   */\n";
      );
      pr "  ";
-      generate_java_prototype ~public:true ~semicolon:false name style;
+      generate_java_prototype ~public:true ~semicolon:false f.name f.style;
      pr "\n";
      pr "  {\n";
      pr "    if (g == 0)\n";
      pr "      throw new LibGuestFSException (\"%s: handle is closed\");\n"
-        name;
+        f.name;
      if optargs <> [] then (
        pr "\n";
        pr "    /* Unpack optional args. */\n";
@@ -313,12 +313,12 @@ public class GuestFS {
      pr "\n";
      (match ret with
       | RErr ->
-           pr "    _%s " name;
-           generate_java_call_args ~handle:"g" style;
+           pr "    _%s " f.name;
+           generate_java_call_args ~handle:"g" f.style;
           pr ";\n"
       | RHashtable _ ->
-           pr "    String[] r = _%s " name;
-           generate_java_call_args ~handle:"g" style;
+           pr "    String[] r = _%s " f.name;
+           generate_java_call_args ~handle:"g" f.style;
           pr ";\n";
           pr "\n";
           pr "    HashMap<String, String> rhash = new HashMap<String, String> ();\n";
@@ -326,8 +326,8 @@ public class GuestFS {
           pr "      rhash.put (r[i], r[i+1]);\n";
           pr "    return rhash;\n"
       | _ ->
-           pr "    return _%s " name;
-           generate_java_call_args ~handle:"g" style;
+           pr "    return _%s " f.name;
+           generate_java_call_args ~handle:"g" f.style;
           pr ";\n"
      );
      pr "  }\n";
@@ -340,14 +340,14 @@ public class GuestFS {
      if optargs <> [] then (
        pr "  ";
        generate_java_prototype ~public:true ~semicolon:false
-          name (ret, args, []);
+          f.name (ret, args, []);
        pr "\n";
        pr "  {\n";
        (match ret with
        | RErr -> pr "    "
        | _ ->    pr "    return "
        );
-        pr "%s (" name;
+        pr "%s (" f.name;
        List.iter (fun arg -> pr "%s, " (name_of_argt arg)) args;
        pr "null);\n";
        pr "  }\n";
@@ -358,14 +358,14 @@ public class GuestFS {
      List.iter (
        fun alias ->
          pr "  ";
-          generate_java_prototype ~public:true ~semicolon:false alias style;
+          generate_java_prototype ~public:true ~semicolon:false alias f.style;
          pr "\n";
          pr "  {\n";
          (match ret with
          | RErr -> pr "    "
          | _ ->    pr "    return "
          );
-          pr "%s (" name;
+          pr "%s (" f.name;
          let needs_comma = ref false in
          List.iter (
            fun arg ->
@@ -392,20 +392,20 @@ public class GuestFS {
            | RErr -> pr "    "
            | _ ->    pr "    return "
            );
-            pr "%s (" name;
+            pr "%s (" f.name;
            List.iter (fun arg -> pr "%s, " (name_of_argt arg)) args;
            pr "null);\n";
            pr "  }\n";
            pr "\n"
          )
-      ) non_c_aliases;
+      ) f.non_c_aliases;

      (* Prototype for the native method. *)
      pr "  ";
-      generate_java_prototype ~privat:true ~native:true name style;
+      generate_java_prototype ~privat:true ~native:true f.name f.style;
      pr "\n";
      pr "\n";
-  ) all_functions;
+  ) external_functions;

  pr "}\n"

@@ -1100,7 +1100,7 @@ get_all_event_callbacks (guestfs_h *g, size_t *len_rtn)

      pr "}\n";
      pr "\n"
-  ) all_functions
+  ) external_functions

 and generate_java_struct_return typ jtyp cols =
  pr "  cl = (*env)->FindClass (env, \"com/redhat/et/libguestfs/%s\");\n" jtyp;
@@ -1191,7 +1191,7 @@ and generate_java_struct_list_return typ jtyp cols =
 and generate_java_makefile_inc () =
  generate_header HashStyle GPLv2plus;

-  let jtyps = List.map (fun { s_camel_name = jtyp } -> jtyp) structs in
+  let jtyps = List.map (fun { s_camel_name = jtyp } -> jtyp) external_structs in
  let jtyps = List.sort compare jtyps in

  pr "java_built_sources = \\\n";
@@ -1201,7 +1201,7 @@ and generate_java_makefile_inc () =
  pr "\tcom/redhat/et/libguestfs/GuestFS.java\n"

 and generate_java_gitignore () =
-  let jtyps = List.map (fun { s_camel_name = jtyp } -> jtyp) structs in
+  let jtyps = List.map (fun { s_camel_name = jtyp } -> jtyp) external_structs in
  let jtyps = List.sort compare jtyps in

  List.iter (pr "%s.java\n") jtyps
--- a/generator/lua.ml
+++ b/generator/lua.ml
@@ -107,7 +107,7 @@ static void free_strings (char **r);
    | typ, (RStructListOnly | RStructAndList) ->
      pr "static void push_%s (lua_State *L, struct guestfs_%s *v);\n" typ typ;
      pr "static void push_%s_list (lua_State *L, struct guestfs_%s_list *v);\n" typ typ
-  ) (rstructs_used_by all_functions);
+  ) (rstructs_used_by external_functions);

  pr "\

@@ -626,7 +626,7 @@ guestfs_lua_delete_event_callback (lua_State *L)
        pr "  return 1;\n";
      pr "}\n";
      pr "\n"
-  ) all_functions_sorted;
+  ) external_functions_sorted;

  pr "\
 static struct userdata *
@@ -863,7 +863,7 @@ push_event (lua_State *L, uint64_t event)
    | typ, (RStructListOnly | RStructAndList) ->
      generate_push_struct typ;
      generate_push_struct_list typ
-  ) (rstructs_used_by all_functions);
+  ) (rstructs_used_by external_functions);

  pr "\
 void
@@ -901,7 +901,7 @@ static luaL_Reg methods[] = {

  List.iter (
    fun { name = name } -> pr "  { \"%s\", guestfs_lua_%s },\n" name name
-  ) all_functions_sorted;
+  ) external_functions_sorted;

  pr "\

--- a/generator/main.ml
+++ b/generator/main.ml
@@ -136,7 +136,7 @@ Run it from the top source directory using the command
      let cols = cols_of_struct typ in
      let filename = sprintf "java/com/redhat/et/libguestfs/%s.java" jtyp in
      output_to filename (generate_java_struct jtyp cols)
-  ) structs;
+  ) external_structs;
  delete_except_generated
    ~skip:["java/com/redhat/et/libguestfs/LibGuestFSException.java";
           "java/com/redhat/et/libguestfs/EventCallback.java"]
@@ -186,7 +186,7 @@ Run it from the top source directory using the command
      output_to filename
        (generate_gobject_optargs_source short name optargs f)
    | { style = _, _, [] } -> ()
-  ) all_functions;
+  ) external_functions;
  delete_except_generated "gobject/include/guestfs-gobject/optargs-*.h";
  delete_except_generated "gobject/src/optargs-*.c";

--- a/generator/ocaml.ml
+++ b/generator/ocaml.ml
@@ -130,12 +130,12 @@ val user_cancel : t -> unit

  (* The actions. *)
  List.iter (
-    fun { name = name; style = style; deprecated_by = deprecated_by;
+    fun ({ name = name; style = style; deprecated_by = deprecated_by;
          non_c_aliases = non_c_aliases;
-          in_docs = in_docs; shortdesc = shortdesc } ->
+          shortdesc = shortdesc } as f) ->
      generate_ocaml_prototype name style;

-      if in_docs then (
+      if is_documented f then (
        pr "(** %s" shortdesc;
        (match deprecated_by with
         | None -> ()
@@ -152,7 +152,7 @@ val user_cancel : t -> unit
          generate_ocaml_prototype alias style;
          pr "\n";
      ) non_c_aliases;
-  ) all_functions_sorted;
+  ) external_functions_sorted;

  pr "\
 (** {2 Object-oriented API}
@@ -203,7 +203,7 @@ class guestfs : ?environment:bool -> ?close_on_exit:bool -> unit -> object
        generate_ocaml_function_type style;
        pr "\n"
      ) non_c_aliases
-  ) all_functions_sorted;
+  ) external_functions_sorted;

  pr "end\n"

@@ -268,7 +268,7 @@ let () =
    fun { name = name; style = style; non_c_aliases = non_c_aliases } ->
      generate_ocaml_prototype ~is_external:true name style;
      List.iter (fun alias -> pr "let %s = %s\n" alias name) non_c_aliases
-  ) all_functions_sorted;
+  ) external_functions_sorted;

  (* OO API. *)
  pr "
@@ -297,7 +297,7 @@ class guestfs ?environment ?close_on_exit () =
      );
      List.iter
        (fun alias -> pr "    method %s = self#%s\n" alias name) non_c_aliases
-  ) all_functions_sorted;
+  ) external_functions_sorted;

  pr "  end\n"

@@ -431,7 +431,7 @@ copy_table (char * const * argv)
        (* generate the function for typ *)
        emit_ocaml_copy_list_function typ
    | typ, _ -> () (* empty *)
-  ) (rstructs_used_by all_functions);
+  ) (rstructs_used_by external_functions);

  (* The wrappers. *)
  List.iter (
@@ -668,7 +668,7 @@ copy_table (char * const * argv)
        pr "}\n";
        pr "\n"
      )
-  ) all_functions_sorted
+  ) external_functions_sorted

 and generate_ocaml_structure_decls () =
  List.iter (
--- a/generator/perl.ml
+++ b/generator/perl.ml
@@ -562,7 +562,7 @@ user_cancel (g)
      );

      pr "\n"
-  ) all_functions
+  ) external_functions

 and generate_perl_struct_list_code typ cols name style n =
  pr "      if (r == NULL)\n";
@@ -860,10 +860,8 @@ handlers and threads.
   * they are pulled in from the XS code automatically.
   *)
  List.iter (
-    function
-    | { in_docs = false } -> ()
-    | ({ name = name; style = style; in_docs = true;
-         longdesc = longdesc; non_c_aliases = non_c_aliases } as f) ->
+    fun ({ name = name; style = style;
+           longdesc = longdesc; non_c_aliases = non_c_aliases } as f) ->
      let longdesc = replace_str longdesc "C<guestfs_" "C<$g-E<gt>" in
      pr "=item ";
      generate_perl_prototype name style;
@@ -893,7 +891,7 @@ handlers and threads.
          pr "=pod\n";
          pr "\n";
      ) non_c_aliases
-  ) all_functions_sorted;
+  ) documented_functions_sorted;

  pr "=cut\n\n";

@@ -955,7 +953,7 @@ handlers and threads.
      pr "    name => \"%s\",\n" name;
      pr "    description => %S,\n" shortdesc;
      pr "  },\n";
-  ) all_functions_sorted;
+  ) external_functions_sorted;
  pr ");\n\n";

  pr "# Add aliases to the introspection hash.\n";
@@ -968,7 +966,7 @@ handlers and threads.
          pr "$guestfs_introspection{%s} = \\%%ielem%d;\n" alias !i;
          incr i
      ) non_c_aliases
-  ) all_functions_sorted;
+  ) external_functions_sorted;
  pr "\n";

  (* End of file. *)
--- a/generator/php.ml
+++ b/generator/php.ml
@@ -53,7 +53,7 @@ PHP_FUNCTION (guestfs_last_error);

  List.iter (
    fun { name = name } -> pr "PHP_FUNCTION (guestfs_%s);\n" name
-  ) all_functions_sorted;
+  ) external_functions_sorted;

  pr "\

@@ -113,7 +113,7 @@ static zend_function_entry guestfs_php_functions[] = {

  List.iter (
    fun { name = name } -> pr "  PHP_FE (guestfs_%s, NULL)\n" name
-  ) all_functions_sorted;
+  ) external_functions_sorted;

  pr "  { NULL, NULL, NULL }
 };
@@ -501,7 +501,7 @@ PHP_FUNCTION (guestfs_last_error)

      pr "}\n";
      pr "\n"
-  ) all_functions_sorted
+  ) external_functions_sorted

 and generate_php_struct_code typ cols =
  pr "  array_init (return_value);\n";
--- a/generator/python.ml
+++ b/generator/python.ml
@@ -249,7 +249,7 @@ free_strings (char **argv)
        (* generate the function for typ *)
        emit_put_list_function typ
    | typ, _ -> () (* empty *)
-  ) (rstructs_used_by all_functions);
+  ) (rstructs_used_by external_functions);

  (* Python wrapper functions. *)
  List.iter (
@@ -523,7 +523,7 @@ free_strings (char **argv)
      pr "  return py_r;\n";
      pr "}\n";
      pr "\n"
-  ) all_functions;
+  ) external_functions;

  (* Table of functions. *)
  pr "static PyMethodDef methods[] = {\n";
@@ -537,7 +537,7 @@ free_strings (char **argv)
    fun { name = name } ->
      pr "  { (char *) \"%s\", py_guestfs_%s, METH_VARARGS, NULL },\n"
        name name
-  ) all_functions;
+  ) external_functions;
  pr "  { NULL, NULL, 0, NULL }\n";
  pr "};\n";
  pr "\n";
@@ -729,9 +729,9 @@ class GuestFS(object):
 ";

  List.iter (
-    fun ({ name = name; style = ret, args, optargs; in_docs = in_docs;
-          longdesc = longdesc; non_c_aliases = non_c_aliases } as f) ->
-      pr "    def %s (self" name;
+    fun f ->
+      let ret, args, optargs = f.style in
+      pr "    def %s (self" f.name;
      List.iter (fun arg -> pr ", %s" (name_of_argt arg)) args;
      List.iter (
        fun optarg ->
@@ -739,8 +739,8 @@ class GuestFS(object):
      ) optargs;
      pr "):\n";

-      if in_docs then (
-        let doc = replace_str longdesc "C<guestfs_" "C<g." in
+      if is_documented f then (
+        let doc = replace_str f.longdesc "C<guestfs_" "C<g." in
        let doc =
          match ret with
          | RErr | RInt _ | RInt64 _ | RBool _
@@ -762,7 +762,7 @@ class GuestFS(object):
          match deprecation_notice f with
          | None -> doc
          | Some txt -> doc ^ "\n\n" ^ txt in
-        let doc = pod2text ~width:60 name doc 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
        pr "        \"\"\"%s\"\"\"\n" doc;
@@ -780,7 +780,7 @@ class GuestFS(object):
            pr "        %s = list (%s)\n" n n
      ) args;
      pr "        self._check_not_closed ()\n";
-      pr "        return libguestfsmod.%s (self._o" name;
+      pr "        return libguestfsmod.%s (self._o" f.name;
      List.iter (fun arg -> pr ", %s" (name_of_argt arg))
        (args @ args_of_optargs optargs);
      pr ")\n\n";
@@ -788,6 +788,6 @@ class GuestFS(object):
      (* Aliases. *)
      List.iter (
        fun alias ->
-          pr "    %s = %s\n\n" alias name
-      ) non_c_aliases
-  ) all_functions
+          pr "    %s = %s\n\n" alias f.name
+      ) f.non_c_aliases
+  ) external_functions
--- a/generator/ruby.ml
+++ b/generator/ruby.ml
@@ -399,13 +399,12 @@ ruby_user_cancel (VALUE gv)
 ";

  List.iter (
-    fun ({ name = name; style = (ret, args, optargs as style);
-           in_docs = in_docs;
-           c_function = c_function; c_optarg_prefix = c_optarg_prefix;
-           shortdesc = shortdesc; longdesc = longdesc } as f) ->
+    fun f ->
+      let ret, args, optargs = f.style in
+
      (* Generate rdoc. *)
-      if in_docs then (
-        let doc = replace_str longdesc "C<guestfs_" "C<g." in
+      if is_documented f then (
+        let doc = replace_str f.longdesc "C<guestfs_" "C<g." in
        let doc =
          if optargs <> [] then
            doc ^ "\n\nOptional arguments are supplied in the final hash parameter, which is a hash of the argument name to its value.  Pass an empty {} for no optional arguments."
@@ -418,7 +417,7 @@ ruby_user_cancel (VALUE gv)
          match deprecation_notice f with
          | None -> doc
          | Some txt -> doc ^ "\n\n" ^ txt in
-        let doc = pod2text ~width:60 name doc in
+        let doc = pod2text ~width:60 f.name doc in
        let doc = String.concat "\n * " doc in
        let doc = trim doc in

@@ -458,7 +457,7 @@ ruby_user_cancel (VALUE gv)
 * (For the C API documentation for this function, see
 * +guestfs_%s+[http://libguestfs.org/guestfs.3.html#guestfs_%s]).
 */
-" name args ret shortdesc doc name name
+" f.name args ret f.shortdesc doc f.name f.name
      );

      (* Generate the function.  Prototype is completely different
@@ -468,7 +467,7 @@ ruby_user_cancel (VALUE gv)
       * http://stackoverflow.com/questions/7626745/extending-ruby-in-c-how-to-specify-default-argument-values-to-function
       *)
      pr "static VALUE\n";
-      pr "ruby_guestfs_%s (" name;
+      pr "ruby_guestfs_%s (" f.name;
      if optargs = [] then (
        pr "VALUE gv";
        List.iter
@@ -482,7 +481,7 @@ ruby_user_cancel (VALUE gv)
      pr "  Data_Get_Struct (gv, guestfs_h, g);\n";
      pr "  if (!g)\n";
      pr "    rb_raise (rb_eArgError, \"%%s: used handle after closing it\", \"%s\");\n"
-        name;
+        f.name;
      pr "\n";

      (* For optargs case, get the arg VALUEs into local variables.
@@ -514,7 +513,7 @@ ruby_user_cancel (VALUE gv)
          pr "  const char *%s = RSTRING_PTR (%sv);\n" n n;
          pr "  if (!%s)\n" n;
          pr "    rb_raise (rb_eTypeError, \"expected string for parameter %%s of %%s\",\n";
-          pr "              \"%s\", \"%s\");\n" n name;
+          pr "              \"%s\", \"%s\");\n" n f.name;
          pr "  size_t %s_size = RSTRING_LEN (%sv);\n" n n
        | OptString n ->
          pr "  const char *%s = !NIL_P (%sv) ? StringValueCStr (%sv) : NULL;\n" n n n
@@ -546,8 +545,8 @@ ruby_user_cancel (VALUE gv)
      (* Optional arguments are passed in a final hash parameter. *)
      if optargs <> [] then (
        pr "  Check_Type (optargsv, T_HASH);\n";
-        pr "  struct %s optargs_s = { .bitmask = 0 };\n" c_function;
-        pr "  struct %s *optargs = &optargs_s;\n" c_function;
+        pr "  struct %s optargs_s = { .bitmask = 0 };\n" f.c_function;
+        pr "  struct %s *optargs = &optargs_s;\n" f.c_function;
        pr "  volatile VALUE v;\n";
        List.iter (
          fun argt ->
@@ -580,7 +579,7 @@ ruby_user_cancel (VALUE gv)
               pr "    optargs_s.%s = r;\n" n;
               pr "  }\n"
            );
-            pr "    optargs_s.bitmask |= %s_%s_BITMASK;\n" c_optarg_prefix uc_n;
+            pr "    optargs_s.bitmask |= %s_%s_BITMASK;\n" f.c_optarg_prefix uc_n;
            pr "  }\n";
        ) optargs;
        pr "\n";
@@ -602,8 +601,8 @@ ruby_user_cancel (VALUE gv)
      );
      pr "\n";

-      pr "  r = %s " c_function;
-      generate_c_call_args ~handle:"g" style;
+      pr "  r = %s " f.c_function;
+      generate_c_call_args ~handle:"g" f.style;
      pr ";\n";

      List.iter (
@@ -678,7 +677,7 @@ ruby_user_cancel (VALUE gv)

      pr "}\n";
      pr "\n"
-  ) all_functions;
+  ) external_functions;

  pr "\
 extern void Init__guestfs (void); /* keep GCC warnings happy */
@@ -731,7 +730,7 @@ Init__guestfs (void)
          pr "  rb_define_method (c_guestfs, \"%s\",\n" alias;
          pr "        ruby_guestfs_%s, %d);\n" name nr_args
      ) non_c_aliases
-  ) all_functions;
+  ) external_functions;

  pr "}\n"

--- a/generator/types.ml
+++ b/generator/types.ml
@@ -368,6 +368,14 @@ and test_init =
 and seq = cmd list
 and cmd = string list

+type visibility =
+  | VPublic                       (* Part of the public API *)
+  | VStateTest                    (* A function which tests the state
+                                     of the appliance *)
+  | VBindTest                     (* Only used for testing language bindings *)
+  | VDebug                        (* Exported everywhere, but not documented *)
+  | VInternal                     (* Not exported *)
+
 (* Type of an action as declared in Actions module. *)
 type action = {
  name : string;                  (* name, not including "guestfs_" *)
@@ -381,10 +389,7 @@ type action = {
  protocol_limit_warning : bool;  (* warn about protocol size limits *)
  fish_alias : string list;       (* alias(es) for this cmd in guestfish *)
  fish_output : fish_output_t option; (* how to display output in guestfish *)
-  in_fish : bool;                 (* export via guestfish *)
-  in_docs : bool;                 (* add this function to documentation *)
-  internal: bool;                 (* function is not part of the
-                                     external api *)
+  visibility: visibility;         (* The visbility of function *)
  deprecated_by : string option;  (* function is deprecated, use .. instead *)
  optional : string option;       (* function is part of an optional group *)
  progress : bool;                (* function can generate progress messages *)