diff --git a/generator/GObject.ml b/generator/GObject.ml
index eada33cee..cb96eb9cb 100644
--- a/generator/GObject.ml
+++ b/generator/GObject.ml
@@ -1118,9 +1118,11 @@ guestfs_session_close (GuestfsSession *session, GError **err)
       );
       pr "\n";
       (match deprecated_by with
-      | None -> ()
-      | Some alt ->
+      | Not_deprecated -> ()
+      | Replaced_by alt ->
         pr " * Deprecated: In new code, use guestfs_session_%s() instead\n" alt
+      | Deprecated_no_replacement ->
+        pr " * Deprecated: There is no documented replacement\n"
       );
       (match version_added f with
       | None -> ()
diff --git a/generator/OCaml.ml b/generator/OCaml.ml
index 083e50530..40fd9454f 100644
--- a/generator/OCaml.ml
+++ b/generator/OCaml.ml
@@ -186,10 +186,13 @@ end
             opt
       );
       (match f.deprecated_by with
-       | None -> ()
-       | Some replacement ->
+       | Not_deprecated -> ()
+       | Replaced_by replacement ->
           has_tags := true;
           pr "\n\n    @deprecated Use {!%s} instead" replacement
+       | Deprecated_no_replacement ->
+          has_tags := true;
+          pr "\n\n    @deprecated There is no documented replacement"
       );
       (match version_added f with
        | None -> ()
diff --git a/generator/actions_core_deprecated.ml b/generator/actions_core_deprecated.ml
index b8cca791b..5d13187ea 100644
--- a/generator/actions_core_deprecated.ml
+++ b/generator/actions_core_deprecated.ml
@@ -28,7 +28,7 @@ let non_daemon_functions = [
     name = "wait_ready"; added = (0, 0, 3);
     style = RErr, [], [];
     visibility = VStateTest;
-    deprecated_by = Some "launch";
+    deprecated_by = Deprecated_no_replacement;
     blocking = false;
     shortdesc = "wait until the hypervisor launches (no op)";
     longdesc = "\
@@ -46,7 +46,7 @@ versions of the API." };
   { defaults with
     name = "kill_subprocess"; added = (0, 0, 3);
     style = RErr, [], [];
-    deprecated_by = Some "shutdown";
+    deprecated_by = Replaced_by "shutdown";
     shortdesc = "kill the hypervisor";
     longdesc = "\
 This kills the hypervisor.
@@ -56,7 +56,7 @@ Do not call this.  See: C<guestfs_shutdown> instead." };
   { defaults with
     name = "add_cdrom"; added = (0, 0, 3);
     style = RErr, [String "filename"], [];
-    deprecated_by = Some "add_drive_ro"; config_only = true;
+    deprecated_by = Replaced_by "add_drive_ro"; config_only = true;
     blocking = false;
     shortdesc = "add a CD-ROM disk image to examine";
     longdesc = "\
@@ -68,7 +68,7 @@ of C<guestfs_add_drive_ro>." };
   { defaults with
     name = "add_drive_with_if"; added = (1, 0, 84);
     style = RErr, [String "filename"; String "iface"], [];
-    deprecated_by = Some "add_drive"; config_only = true;
+    deprecated_by = Replaced_by "add_drive"; config_only = true;
     blocking = false;
     shortdesc = "add a drive specifying the QEMU block emulation to use";
     longdesc = "\
@@ -79,7 +79,7 @@ to specify the QEMU interface emulation to use at run time." };
     name = "add_drive_ro_with_if"; added = (1, 0, 84);
     style = RErr, [String "filename"; String "iface"], [];
     blocking = false;
-    deprecated_by = Some "add_drive"; config_only = true;
+    deprecated_by = Replaced_by "add_drive"; config_only = true;
     shortdesc = "add a drive read-only specifying the QEMU block emulation to use";
     longdesc = "\
 This is the same as C<guestfs_add_drive_ro> but it allows you
@@ -88,7 +88,7 @@ to specify the QEMU interface emulation to use at run time." };
   { defaults with
     name = "lstatlist"; added = (1, 0, 77);
     style = RStructList ("statbufs", "stat"), [Pathname "path"; FilenameList "names"], [];
-    deprecated_by = Some "lstatnslist";
+    deprecated_by = Replaced_by "lstatnslist";
     shortdesc = "lstat on multiple files";
     longdesc = "\
 This call allows you to perform the C<guestfs_lstat> operation
@@ -108,7 +108,7 @@ for getting extended attributes." };
   { defaults with
     name = "stat"; added = (1, 9, 2);
     style = RStruct ("statbuf", "stat"), [Pathname "path"], [];
-    deprecated_by = Some "statns";
+    deprecated_by = Replaced_by "statns";
     tests = [
       InitISOFS, Always, TestResult (
         [["stat"; "/empty"]], "ret->size == 0"), []
@@ -122,7 +122,7 @@ This is the same as the L<stat(2)> system call." };
   { defaults with
     name = "lstat"; added = (1, 9, 2);
     style = RStruct ("statbuf", "stat"), [Pathname "path"], [];
-    deprecated_by = Some "lstatns";
+    deprecated_by = Replaced_by "lstatns";
     tests = [
       InitISOFS, Always, TestResult (
         [["lstat"; "/empty"]], "ret->size == 0"), []
@@ -145,7 +145,7 @@ let daemon_functions = [
     style = RErr, [Device "device";
                    Int "cyls"; Int "heads"; Int "sectors";
                    StringList "lines"], [];
-    deprecated_by = Some "part_add";
+    deprecated_by = Replaced_by "part_add";
     shortdesc = "create partitions on a block device";
     longdesc = "\
 This is a direct interface to the L<sfdisk(8)> program for creating
@@ -174,7 +174,7 @@ C<guestfs_part_init>" };
   { defaults with
     name = "blockdev_setbsz"; added = (1, 9, 3);
     style = RErr, [Device "device"; Int "blocksize"], [];
-    deprecated_by = Some "mkfs";
+    deprecated_by = Deprecated_no_replacement;
     shortdesc = "set blocksize of block device";
     longdesc = "\
 This call does nothing and has never done anything
@@ -186,7 +186,7 @@ C<blocksize> option of C<guestfs_mkfs>." };
   { defaults with
     name = "tgz_in"; added = (1, 0, 3);
     style = RErr, [FileIn "tarball"; Pathname "directory"], [];
-    deprecated_by = Some "tar_in";
+    deprecated_by = Replaced_by "tar_in";
     cancellable = true;
     tests = [
       InitScratchFS, Always, TestResultString (
@@ -202,7 +202,7 @@ I<gzip compressed> tar file) into F<directory>." };
   { defaults with
     name = "tgz_out"; added = (1, 0, 3);
     style = RErr, [Pathname "directory"; FileOut "tarball"], [];
-    deprecated_by = Some "tar_out";
+    deprecated_by = Replaced_by "tar_out";
     cancellable = true;
     shortdesc = "pack directory into compressed tarball";
     longdesc = "\
@@ -212,7 +212,7 @@ it to local file C<tarball>." };
   { defaults with
     name = "set_e2label"; added = (1, 0, 15);
     style = RErr, [Device "device"; String "label"], [];
-    deprecated_by = Some "set_label";
+    deprecated_by = Replaced_by "set_label";
     tests = [
       InitBasicFS, Always, TestResultString (
         [["set_e2label"; "/dev/sda1"; "testlabel"];
@@ -230,7 +230,7 @@ to return the existing label on a filesystem." };
   { defaults with
     name = "get_e2label"; added = (1, 0, 15);
     style = RString "label", [Device "device"], [];
-    deprecated_by = Some "vfs_label";
+    deprecated_by = Replaced_by "vfs_label";
     shortdesc = "get the ext2/3/4 filesystem label";
     longdesc = "\
 This returns the ext2/3/4 filesystem label of the filesystem on
@@ -239,7 +239,7 @@ C<device>." };
   { defaults with
     name = "set_e2uuid"; added = (1, 0, 15);
     style = RErr, [Device "device"; String "uuid"], [];
-    deprecated_by = Some "set_uuid";
+    deprecated_by = Replaced_by "set_uuid";
     tests = [
         InitBasicFS, Always, TestResultString (
           [["set_e2uuid"; "/dev/sda1"; stable_uuid];
@@ -267,7 +267,7 @@ of a filesystem." };
   { defaults with
     name = "get_e2uuid"; added = (1, 0, 15);
     style = RString "uuid", [Device "device"], [];
-    deprecated_by = Some "vfs_uuid";
+    deprecated_by = Replaced_by "vfs_uuid";
     tests = [
       (* We can't predict what UUID will be, so just check
          the command run; regression test for RHBZ#597112. *)
@@ -285,7 +285,7 @@ C<device>." };
     style = RErr, [Device "device"; Int "partnum";
                    Int "cyls"; Int "heads"; Int "sectors";
                    String "line"], [];
-    deprecated_by = Some "part_add";
+    deprecated_by = Replaced_by "part_add";
     shortdesc = "modify a single partition on a block device";
     longdesc = "\
 This runs L<sfdisk(8)> option to modify just the single
@@ -299,7 +299,7 @@ See also: C<guestfs_part_add>" };
   { defaults with
     name = "sfdisk_l"; added = (1, 0, 26);
     style = RString "partitions", [Device "device"], [];
-    deprecated_by = Some "part_list";
+    deprecated_by = Replaced_by "part_list";
     shortdesc = "display the partition table";
     longdesc = "\
 This displays the partition table on C<device>, in the
@@ -311,7 +311,7 @@ See also: C<guestfs_part_list>" };
   { defaults with
     name = "e2fsck_f"; added = (1, 0, 29);
     style = RErr, [Device "device"], [];
-    deprecated_by = Some "e2fsck";
+    deprecated_by = Replaced_by "e2fsck";
     shortdesc = "check an ext2/ext3 filesystem";
     longdesc = "\
 This runs C<e2fsck -p -f device>, ie. runs the ext2/ext3
@@ -321,7 +321,7 @@ even if the filesystem appears to be clean (I<-f>)." };
   { defaults with
     name = "mkswap_L"; added = (1, 0, 55);
     style = RErr, [String "label"; Device "device"], [];
-    deprecated_by = Some "mkswap";
+    deprecated_by = Replaced_by "mkswap";
     tests = [
       InitEmpty, Always, TestRun (
         [["part_disk"; "/dev/sda"; "mbr"];
@@ -338,7 +338,7 @@ a limitation of the kernel or swap tools." };
   { defaults with
     name = "mkswap_U"; added = (1, 0, 55);
     style = RErr, [String "uuid"; Device "device"], [];
-    deprecated_by = Some "mkswap";
+    deprecated_by = Replaced_by "mkswap";
     optional = Some "linuxfsuuid";
     tests = [
         InitEmpty, Always, TestRun (
@@ -352,7 +352,7 @@ Create a swap partition on C<device> with UUID C<uuid>." };
   { defaults with
     name = "sfdiskM"; added = (1, 0, 55);
     style = RErr, [Device "device"; StringList "lines"], [];
-    deprecated_by = Some "part_add";
+    deprecated_by = Replaced_by "part_add";
     shortdesc = "create partitions on a block device";
     longdesc = "\
 This is a simplified interface to the C<guestfs_sfdisk>
@@ -367,7 +367,7 @@ and C<guestfs_part_disk>" };
   { defaults with
     name = "zfile"; added = (1, 0, 59);
     style = RString "description", [String "meth"; Pathname "path"], [];
-    deprecated_by = Some "file";
+    deprecated_by = Replaced_by "file";
     shortdesc = "determine file type inside a compressed file";
     longdesc = "\
 This command runs F<file> after first decompressing C<path>
@@ -382,7 +382,7 @@ process compressed files." };
     name = "egrep"; added = (1, 0, 66);
     style = RStringList "lines", [String "regex"; Pathname "path"], [];
     protocol_limit_warning = true;
-    deprecated_by = Some "grep";
+    deprecated_by = Replaced_by "grep";
     tests = [
       InitISOFS, Always, TestResult (
         [["egrep"; "abc"; "/test-grep.txt"]],
@@ -397,7 +397,7 @@ matching lines." };
     name = "fgrep"; added = (1, 0, 66);
     style = RStringList "lines", [String "pattern"; Pathname "path"], [];
     protocol_limit_warning = true;
-    deprecated_by = Some "grep";
+    deprecated_by = Replaced_by "grep";
     tests = [
       InitISOFS, Always, TestResult (
         [["fgrep"; "abc"; "/test-grep.txt"]],
@@ -412,7 +412,7 @@ matching lines." };
     name = "grepi"; added = (1, 0, 66);
     style = RStringList "lines", [String "regex"; Pathname "path"], [];
     protocol_limit_warning = true;
-    deprecated_by = Some "grep";
+    deprecated_by = Replaced_by "grep";
     tests = [
       InitISOFS, Always, TestResult (
         [["grepi"; "abc"; "/test-grep.txt"]],
@@ -427,7 +427,7 @@ matching lines." };
     name = "egrepi"; added = (1, 0, 66);
     style = RStringList "lines", [String "regex"; Pathname "path"], [];
     protocol_limit_warning = true;
-    deprecated_by = Some "grep";
+    deprecated_by = Replaced_by "grep";
     tests = [
       InitISOFS, Always, TestResult (
         [["egrepi"; "abc"; "/test-grep.txt"]],
@@ -442,7 +442,7 @@ matching lines." };
     name = "fgrepi"; added = (1, 0, 66);
     style = RStringList "lines", [String "pattern"; Pathname "path"], [];
     protocol_limit_warning = true;
-    deprecated_by = Some "grep";
+    deprecated_by = Replaced_by "grep";
     tests = [
       InitISOFS, Always, TestResult (
         [["fgrepi"; "abc"; "/test-grep.txt"]],
@@ -457,7 +457,7 @@ matching lines." };
     name = "zgrep"; added = (1, 0, 66);
     style = RStringList "lines", [String "regex"; Pathname "path"], [];
     protocol_limit_warning = true;
-    deprecated_by = Some "grep";
+    deprecated_by = Replaced_by "grep";
     tests = [
       InitISOFS, Always, TestResult (
         [["zgrep"; "abc"; "/test-grep.txt.gz"]],
@@ -472,7 +472,7 @@ matching lines." };
     name = "zegrep"; added = (1, 0, 66);
     style = RStringList "lines", [String "regex"; Pathname "path"], [];
     protocol_limit_warning = true;
-    deprecated_by = Some "grep";
+    deprecated_by = Replaced_by "grep";
     tests = [
       InitISOFS, Always, TestResult (
         [["zegrep"; "abc"; "/test-grep.txt.gz"]],
@@ -487,7 +487,7 @@ matching lines." };
     name = "zfgrep"; added = (1, 0, 66);
     style = RStringList "lines", [String "pattern"; Pathname "path"], [];
     protocol_limit_warning = true;
-    deprecated_by = Some "grep";
+    deprecated_by = Replaced_by "grep";
     tests = [
       InitISOFS, Always, TestResult (
         [["zfgrep"; "abc"; "/test-grep.txt.gz"]],
@@ -503,7 +503,7 @@ matching lines." };
     style = RStringList "lines", [String "regex"; Pathname "path"], [];
 
     protocol_limit_warning = true;
-    deprecated_by = Some "grep";
+    deprecated_by = Replaced_by "grep";
     tests = [
       InitISOFS, Always, TestResult (
         [["zgrepi"; "abc"; "/test-grep.txt.gz"]],
@@ -518,7 +518,7 @@ matching lines." };
     name = "zegrepi"; added = (1, 0, 66);
     style = RStringList "lines", [String "regex"; Pathname "path"], [];
     protocol_limit_warning = true;
-    deprecated_by = Some "grep";
+    deprecated_by = Replaced_by "grep";
     tests = [
       InitISOFS, Always, TestResult (
         [["zegrepi"; "abc"; "/test-grep.txt.gz"]],
@@ -533,7 +533,7 @@ matching lines." };
     name = "zfgrepi"; added = (1, 0, 66);
     style = RStringList "lines", [String "pattern"; Pathname "path"], [];
     protocol_limit_warning = true;
-    deprecated_by = Some "grep";
+    deprecated_by = Replaced_by "grep";
     tests = [
       InitISOFS, Always, TestResult (
         [["zfgrepi"; "abc"; "/test-grep.txt.gz"]],
@@ -547,7 +547,7 @@ matching lines." };
   { defaults with
     name = "fallocate"; added = (1, 0, 66);
     style = RErr, [Pathname "path"; Int "len"], [];
-    deprecated_by = Some "fallocate64";
+    deprecated_by = Replaced_by "fallocate64";
     tests = [
       InitScratchFS, Always, TestResult (
         [["fallocate"; "/fallocate"; "1000000"];
@@ -567,7 +567,7 @@ attaches it as a device." };
     name = "setcon"; added = (1, 0, 67);
     style = RErr, [String "context"], [];
     optional = Some "selinux";
-    deprecated_by = Some "selinux_relabel";
+    deprecated_by = Replaced_by "selinux_relabel";
     shortdesc = "set SELinux security context";
     longdesc = "\
 This sets the SELinux security context of the daemon
@@ -579,7 +579,7 @@ See the documentation about SELINUX in L<guestfs(3)>." };
     name = "getcon"; added = (1, 0, 67);
     style = RString "context", [], [];
     optional = Some "selinux";
-    deprecated_by = Some "selinux_relabel";
+    deprecated_by = Replaced_by "selinux_relabel";
     shortdesc = "get SELinux security context";
     longdesc = "\
 This gets the SELinux security context of the daemon.
@@ -590,7 +590,7 @@ and C<guestfs_setcon>" };
   { defaults with
     name = "mkfs_b"; added = (1, 0, 68);
     style = RErr, [String "fstype"; Int "blocksize"; Device "device"], [];
-    deprecated_by = Some "mkfs";
+    deprecated_by = Replaced_by "mkfs";
     tests = [
       InitEmpty, Always, TestResultString (
         [["part_disk"; "/dev/sda"; "mbr"];
@@ -627,7 +627,7 @@ the requested cluster size." };
   { defaults with
     name = "mke2journal"; added = (1, 0, 68);
     style = RErr, [Int "blocksize"; Device "device"], [];
-    deprecated_by = Some "mke2fs";
+    deprecated_by = Replaced_by "mke2fs";
     tests = [
       InitEmpty, Always, TestResultString (
         [["part_init"; "/dev/sda"; "mbr"];
@@ -649,7 +649,7 @@ to the command:
   { defaults with
     name = "mke2journal_L"; added = (1, 0, 68);
     style = RErr, [Int "blocksize"; String "label"; Device "device"], [];
-    deprecated_by = Some "mke2fs";
+    deprecated_by = Replaced_by "mke2fs";
     tests = [
       InitEmpty, Always, TestResultString (
         [["part_init"; "/dev/sda"; "mbr"];
@@ -668,7 +668,7 @@ This creates an ext2 external journal on C<device> with label C<label>." };
   { defaults with
     name = "mke2journal_U"; added = (1, 0, 68);
     style = RErr, [Int "blocksize"; String "uuid"; Device "device"], [];
-    deprecated_by = Some "mke2fs";
+    deprecated_by = Replaced_by "mke2fs";
     optional = Some "linuxfsuuid";
     tests = [
         InitEmpty, Always, TestResultString (
@@ -688,7 +688,7 @@ This creates an ext2 external journal on C<device> with UUID C<uuid>." };
   { defaults with
     name = "mke2fs_J"; added = (1, 0, 68);
     style = RErr, [String "fstype"; Int "blocksize"; Device "device"; Device "journal"], [];
-    deprecated_by = Some "mke2fs";
+    deprecated_by = Replaced_by "mke2fs";
     shortdesc = "make ext2/3/4 filesystem with external journal";
     longdesc = "\
 This creates an ext2/3/4 filesystem on C<device> with
@@ -702,7 +702,7 @@ See also C<guestfs_mke2journal>." };
   { defaults with
     name = "mke2fs_JL"; added = (1, 0, 68);
     style = RErr, [String "fstype"; Int "blocksize"; Device "device"; String "label"], [];
-    deprecated_by = Some "mke2fs";
+    deprecated_by = Replaced_by "mke2fs";
     shortdesc = "make ext2/3/4 filesystem with external journal";
     longdesc = "\
 This creates an ext2/3/4 filesystem on C<device> with
@@ -713,7 +713,7 @@ See also C<guestfs_mke2journal_L>." };
   { defaults with
     name = "mke2fs_JU"; added = (1, 0, 68);
     style = RErr, [String "fstype"; Int "blocksize"; Device "device"; String "uuid"], [];
-    deprecated_by = Some "mke2fs";
+    deprecated_by = Replaced_by "mke2fs";
     optional = Some "linuxfsuuid";
     shortdesc = "make ext2/3/4 filesystem with external journal";
     longdesc = "\
@@ -725,7 +725,7 @@ See also C<guestfs_mke2journal_U>." };
   { defaults with
     name = "dd"; added = (1, 0, 80);
     style = RErr, [Dev_or_Path "src"; Dev_or_Path "dest"], [];
-    deprecated_by = Some "copy_device_to_device";
+    deprecated_by = Replaced_by "copy_device_to_device";
     tests = [
       InitScratchFS, Always, TestResult (
         [["mkdir"; "/dd"];
@@ -749,7 +749,7 @@ This command cannot do partial copies
   { defaults with
     name = "txz_in"; added = (1, 3, 2);
     style = RErr, [FileIn "tarball"; Pathname "directory"], [];
-    deprecated_by = Some "tar_in";
+    deprecated_by = Replaced_by "tar_in";
     optional = Some "xz"; cancellable = true;
     tests = [
       InitScratchFS, Always, TestResultString (
@@ -765,7 +765,7 @@ I<xz compressed> tar file) into F<directory>." };
   { defaults with
     name = "txz_out"; added = (1, 3, 2);
     style = RErr, [Pathname "directory"; FileOut "tarball"], [];
-    deprecated_by = Some "tar_out";
+    deprecated_by = Replaced_by "tar_out";
     optional = Some "xz"; cancellable = true;
     shortdesc = "pack directory into compressed tarball";
     longdesc = "\
@@ -775,7 +775,7 @@ it to local file C<tarball> (as an xz compressed tar archive)." };
   { defaults with
     name = "llz"; added = (1, 17, 6);
     style = RString "listing", [Pathname "directory"], [];
-    deprecated_by = Some "lgetxattrs";
+    deprecated_by = Replaced_by "lgetxattrs";
     shortdesc = "list the files in a directory (long format with SELinux contexts)";
     longdesc = "\
 List the files in F<directory> in the format of 'ls -laZ'.
@@ -786,7 +786,7 @@ is I<not> intended that you try to parse the output string." };
   { defaults with
     name = "write_file"; added = (0, 0, 8);
     style = RErr, [Pathname "path"; String "content"; Int "size"], [];
-    protocol_limit_warning = true; deprecated_by = Some "write";
+    protocol_limit_warning = true; deprecated_by = Replaced_by "write";
     (* Regression test for RHBZ#597135. *)
     tests = [
       InitScratchFS, Always, TestLastFail
@@ -808,7 +808,7 @@ characters does I<not> work, even if the length is specified." };
   { defaults with
     name = "copy_size"; added = (1, 0, 87);
     style = RErr, [Dev_or_Path "src"; Dev_or_Path "dest"; Int64 "size"], [];
-    progress = true; deprecated_by = Some "copy_device_to_device";
+    progress = true; deprecated_by = Replaced_by "copy_device_to_device";
     tests = [
       InitScratchFS, Always, TestResult (
         [["mkdir"; "/copy_size"];
@@ -828,7 +828,7 @@ is not large enough." };
   { defaults with
     name = "ntfsresize_size"; added = (1, 3, 14);
     style = RErr, [Device "device"; Int64 "size"], [];
-    optional = Some "ntfsprogs"; deprecated_by = Some "ntfsresize";
+    optional = Some "ntfsprogs"; deprecated_by = Replaced_by "ntfsresize";
     shortdesc = "resize an NTFS filesystem (with size)";
     longdesc = "\
 This command is the same as C<guestfs_ntfsresize> except that it
diff --git a/generator/actions_inspection_deprecated.ml b/generator/actions_inspection_deprecated.ml
index 04fb14311..5ca062cbe 100644
--- a/generator/actions_inspection_deprecated.ml
+++ b/generator/actions_inspection_deprecated.ml
@@ -26,7 +26,7 @@ let non_daemon_functions = [
   { defaults with
     name = "inspect_list_applications"; added = (1, 7, 8);
     style = RStructList ("applications", "application"), [Mountable "root"], [];
-    deprecated_by = Some "inspect_list_applications2";
+    deprecated_by = Replaced_by "inspect_list_applications2";
     shortdesc = "get list of applications installed in the operating system";
     longdesc = "\
 Return the list of applications installed in the operating system.
diff --git a/generator/actions_properties_deprecated.ml b/generator/actions_properties_deprecated.ml
index 3fe8fefd8..def17b926 100644
--- a/generator/actions_properties_deprecated.ml
+++ b/generator/actions_properties_deprecated.ml
@@ -30,7 +30,7 @@ let non_daemon_functions = [
     style = RErr, [OptString "hv"], [];
     fish_alias = ["qemu"]; config_only = true;
     blocking = false;
-    deprecated_by = Some "set_hv";
+    deprecated_by = Replaced_by "set_hv";
     shortdesc = "set the hypervisor binary (usually qemu)";
     longdesc = "\
 Set the hypervisor binary (usually qemu) that we will use.
@@ -55,7 +55,7 @@ the qemu binary at the same time as the handle is created." };
     name = "get_qemu"; added = (1, 0, 6);
     style = RConstString "hv", [], [];
     blocking = false;
-    deprecated_by = Some "get_hv";
+    deprecated_by = Replaced_by "get_hv";
     tests = [
       InitNone, Always, TestRun (
         [["get_qemu"]]), []
@@ -72,7 +72,7 @@ return the default qemu binary name." };
     style = RErr, [Bool "selinux"], [];
     fish_alias = ["selinux"]; config_only = true;
     blocking = false;
-    deprecated_by = Some "selinux_relabel";
+    deprecated_by = Replaced_by "selinux_relabel";
     shortdesc = "set SELinux enabled or disabled at appliance boot";
     longdesc = "\
 This sets the selinux flag that is passed to the appliance
@@ -88,7 +88,7 @@ see L<guestfs(3)>." };
     name = "get_selinux"; added = (1, 0, 67);
     style = RBool "selinux", [], [];
     blocking = false;
-    deprecated_by = Some "selinux_relabel";
+    deprecated_by = Replaced_by "selinux_relabel";
     shortdesc = "get SELinux enabled flag";
     longdesc = "\
 This returns the current setting of the selinux flag which
@@ -102,7 +102,7 @@ see L<guestfs(3)>." };
     style = RErr, [String "backend"], [];
     fish_alias = ["attach-method"]; config_only = true;
     blocking = false;
-    deprecated_by = Some "set_backend";
+    deprecated_by = Replaced_by "set_backend";
     shortdesc = "set the backend";
     longdesc = "\
 Set the method that libguestfs uses to connect to the backend
@@ -114,7 +114,7 @@ See L<guestfs(3)/BACKEND>." };
     name = "get_attach_method"; added = (1, 9, 8);
     style = RString "backend", [], [];
     blocking = false;
-    deprecated_by = Some "get_backend";
+    deprecated_by = Replaced_by "get_backend";
     tests = [
       InitNone, Always, TestRun (
         [["get_attach_method"]]), []
diff --git a/generator/c.ml b/generator/c.ml
index 1cb088061..606c89807 100644
--- a/generator/c.ml
+++ b/generator/c.ml
@@ -445,11 +445,14 @@ extern \"C\" {
 #endif
 
 /* Define GUESTFS_WARN_DEPRECATED=1 to warn about deprecated API functions. */
-#define GUESTFS_DEPRECATED_BY(s)
+#define GUESTFS_DEPRECATED_NO_REPLACEMENT
+#define GUESTFS_DEPRECATED_REPLACED_BY(s)
 #if GUESTFS_WARN_DEPRECATED
 #  if defined(__GNUC__) && GUESTFS_GCC_VERSION >= 40500 /* gcc >= 4.5 */
-#    undef GUESTFS_DEPRECATED_BY
-#    define GUESTFS_DEPRECATED_BY(s) __attribute__((__deprecated__(\"change the program to use guestfs_\" s \" instead of this deprecated function\")))
+#    undef GUESTFS_DEPRECATED_NO_REPLACEMENT
+#    undef GUESTFS_DEPRECATED_REPLACED_BY
+#    define GUESTFS_DEPRECATED_NO_REPLACEMENT __attribute__((__deprecated__))
+#    define GUESTFS_DEPRECATED_REPLACED_BY(s) __attribute__((__deprecated__(\"change the program to use guestfs_\" s \" instead of this deprecated function\")))
 #  endif
 #endif /* GUESTFS_WARN_DEPRECATED */
 
@@ -562,17 +565,17 @@ typedef void (*guestfs_progress_cb) (guestfs_h *g, void *opaque, int proc_nr, in
 #endif
 
 extern GUESTFS_DLL_PUBLIC void guestfs_set_log_message_callback (guestfs_h *g, guestfs_log_message_cb cb, void *opaque)
-  GUESTFS_DEPRECATED_BY(\"set_event_callback\");
+  GUESTFS_DEPRECATED_REPLACED_BY(\"set_event_callback\");
 extern GUESTFS_DLL_PUBLIC void guestfs_set_subprocess_quit_callback (guestfs_h *g, guestfs_subprocess_quit_cb cb, void *opaque)
-  GUESTFS_DEPRECATED_BY(\"set_event_callback\");
+  GUESTFS_DEPRECATED_REPLACED_BY(\"set_event_callback\");
 extern GUESTFS_DLL_PUBLIC void guestfs_set_launch_done_callback (guestfs_h *g, guestfs_launch_done_cb cb, void *opaque)
-  GUESTFS_DEPRECATED_BY(\"set_event_callback\");
+  GUESTFS_DEPRECATED_REPLACED_BY(\"set_event_callback\");
 #define GUESTFS_HAVE_SET_CLOSE_CALLBACK 1
 extern GUESTFS_DLL_PUBLIC void guestfs_set_close_callback (guestfs_h *g, guestfs_close_cb cb, void *opaque)
-  GUESTFS_DEPRECATED_BY(\"set_event_callback\");
+  GUESTFS_DEPRECATED_REPLACED_BY(\"set_event_callback\");
 #define GUESTFS_HAVE_SET_PROGRESS_CALLBACK 1
 extern GUESTFS_DLL_PUBLIC void guestfs_set_progress_callback (guestfs_h *g, guestfs_progress_cb cb, void *opaque)
-  GUESTFS_DEPRECATED_BY(\"set_event_callback\");
+  GUESTFS_DEPRECATED_REPLACED_BY(\"set_event_callback\");
 
 /* Private data area. */
 #define GUESTFS_HAVE_SET_PRIVATE 1
@@ -662,8 +665,12 @@ extern GUESTFS_DLL_PUBLIC void *guestfs_next_private (guestfs_h *g, const char *
     generate_prototype ~single_line:true ~semicolon:false ~dll_public:true
       ~handle:"g" ~prefix:"guestfs_" shortname style;
     (match deprecated_by with
-    | Some fn -> pr "\n  GUESTFS_DEPRECATED_BY (%S);\n" fn
-    | None -> pr ";\n"
+    | Not_deprecated ->
+       pr ";\n"
+    | Replaced_by fn ->
+       pr "\n  GUESTFS_DEPRECATED_REPLACED_BY (%S);\n" fn
+    | Deprecated_no_replacement ->
+       pr "\n  GUESTFS_DEPRECATED_NO_REPLACEMENT;\n"
     );
 
     if optargs <> [] then (
diff --git a/generator/checks.ml b/generator/checks.ml
index 63536e59b..788a11624 100644
--- a/generator/checks.ml
+++ b/generator/checks.ml
@@ -184,7 +184,7 @@ let () =
             failwithf "%s: guestfish alias %s should not contain '_'" name n
       ) f.fish_alias;
       (match f.deprecated_by with
-      | Some n ->
+      | Replaced_by n ->
         (* 'n' must be a cross-ref to the name of another action. *)
         if not (List.exists (
           function
@@ -192,7 +192,7 @@ let () =
           | _ -> false
         ) actions) then
           failwithf "%s: deprecated_by flag must be cross-reference to another action" name
-      | None -> ()
+      | Not_deprecated | Deprecated_no_replacement -> ()
       );
       (match f.optional with
       | Some n ->
diff --git a/generator/docstrings.ml b/generator/docstrings.ml
index acfdb5399..2ce595dae 100644
--- a/generator/docstrings.ml
+++ b/generator/docstrings.ml
@@ -39,8 +39,9 @@ of somewhere between 2MB and 4MB.  See L<guestfs(3)/PROTOCOL LIMITS>."
 
 let deprecation_notice ?(prefix = "") ?(replace_underscores = false) =
   function
-  | { deprecated_by = None } -> None
-  | { deprecated_by = Some alt } ->
+  | { deprecated_by = Not_deprecated } -> None
+
+  | { deprecated_by = Replaced_by alt } ->
     let alt =
       if replace_underscores then String.replace_char alt '_' '-' else alt in
     let txt =
@@ -52,6 +53,15 @@ fact that they are deprecated indicates that there are problems
 with correct use of these functions." prefix alt in
     Some txt
 
+  | { deprecated_by = Deprecated_no_replacement } ->
+     Some "I<This function is deprecated.>
+There is no replacement.  Consult the API documentation in
+L<guestfs(3)> for further information.
+
+Deprecated functions will not be removed from the API, but the
+fact that they are deprecated indicates that there are problems
+with correct use of these functions."
+
 let version_added = function
   | { added = (0, 0, release) } -> Some (sprintf "0.%d" release)
   | { added = ((0|1) as major, minor, release) } ->
diff --git a/generator/java.ml b/generator/java.ml
index 66729c6fe..163a3e8fd 100644
--- a/generator/java.ml
+++ b/generator/java.ml
@@ -297,9 +297,11 @@ public class GuestFS {
         | Some version -> pr "   * @since %s\n" version
         );
         (match f with
-        | { deprecated_by = None } -> ()
-        | { deprecated_by = Some alt } ->
+        | { deprecated_by = Not_deprecated } -> ()
+        | { deprecated_by = Replaced_by alt } ->
           pr "   * @deprecated In new code, use {@link #%s} instead\n" alt
+        | { deprecated_by = Deprecated_no_replacement } ->
+          pr "   * @deprecated There is no documented replacement\n"
         );
         pr "   * @throws LibGuestFSException If there is a libguestfs error.\n";
         pr "   */\n";
@@ -307,8 +309,9 @@ public class GuestFS {
       pr "  ";
       let deprecated =
         match f with
-        | { deprecated_by = None } -> false
-        | { deprecated_by = Some _ } -> true in
+        | { deprecated_by = Not_deprecated } -> false
+        | { deprecated_by = Replaced_by _ | Deprecated_no_replacement } ->
+           true in
       generate_java_prototype ~public:true ~semicolon:false ~deprecated f.name f.style;
       pr "\n";
       pr "  {\n";
diff --git a/generator/ruby.ml b/generator/ruby.ml
index c938bc9e3..dd215d2e5 100644
--- a/generator/ruby.ml
+++ b/generator/ruby.ml
@@ -146,9 +146,12 @@ and generate_ruby_c actions () =
           | Some version -> doc ^ (sprintf "\n *\n * [Since] Added in version %s." version) in
         let doc =
           match f with
-          | { deprecated_by = None } -> doc
-          | { deprecated_by = Some alt } ->
-            doc ^ (sprintf "\n *\n * [Deprecated] In new code, use rdoc-ref:%s instead." alt) in
+          | { deprecated_by = Not_deprecated } -> doc
+          | { deprecated_by = Replaced_by alt } ->
+            doc ^
+              sprintf "\n *\n * [Deprecated] In new code, use rdoc-ref:%s instead." alt
+          | { deprecated_by = Deprecated_no_replacement } ->
+            doc ^ "\n *\n * [Deprecated] There is no documented replacement" in
         let doc =
           match f.optional with
           | None -> doc
diff --git a/generator/types.ml b/generator/types.ml
index fd9f21546..3fa96fd7a 100644
--- a/generator/types.ml
+++ b/generator/types.ml
@@ -342,6 +342,11 @@ type visibility =
 
 type version = int * int * int
 
+type deprecated_by =
+  | Not_deprecated                (* function not deprecated *)
+  | Replaced_by of string         (* replaced by another function *)
+  | Deprecated_no_replacement     (* deprecated with no replacement *)
+
 (* Type of an action as declared in Actions module. *)
 type action = {
   name : string;                  (* name, not including "guestfs_" *)
@@ -358,7 +363,7 @@ type action = {
   fish_alias : string list;       (* alias(es) for this cmd in guestfish *)
   fish_output : fish_output_t option; (* how to display output in guestfish *)
   visibility: visibility;         (* The visbility of function *)
-  deprecated_by : string option;  (* function is deprecated, use .. instead *)
+  deprecated_by : deprecated_by;  (* function is deprecated *)
   optional : string option;       (* function is part of an optional group *)
   progress : bool;                (* function can generate progress messages *)
   camel_name : string;            (* Pretty camel case name of
@@ -407,7 +412,7 @@ let defaults = { name = "";
                  shortdesc = ""; longdesc = "";
                  protocol_limit_warning = false; fish_alias = [];
                  fish_output = None; visibility = VPublic;
-                 deprecated_by = None; optional = None;
+                 deprecated_by = Not_deprecated; optional = None;
                  progress = false; camel_name = "";
                  cancellable = false; config_only = false;
                  once_had_no_optargs = false; blocking = true; wrapper = true;