Libguestfs - Feb 2015 - [PATCH 3/3] ocaml: hide internal methods from apidocs

Generate proper deprecation markers for API documentation and
introspection annotations.
---
 generator/gobject.ml | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/generator/gobject.ml b/generator/gobject.ml
index 5b07edd..e563610 100644
--- a/generator/gobject.ml
+++ b/generator/gobject.ml
@@ -961,7 +961,8 @@ guestfs_session_close (GuestfsSession *session, GError
**err)
     fun ({ name = name; style = (ret, args, optargs as style);
            cancellable = cancellable; c_function = c_function;
            c_optarg_prefix = c_optarg_prefix;
-           shortdesc = shortdesc; longdesc = longdesc } as f) ->
+           shortdesc = shortdesc; longdesc = longdesc;
+           deprecated_by = deprecated_by } as f) ->
       pr "\n";
 
       let longdesc = Str.global_substitute urls (
@@ -1103,6 +1104,11 @@ guestfs_session_close (GuestfsSession *session, GError
**err)
          pr "(transfer full) (array zero-terminated=1) (element-type
Guestfs%s): an array of %s objects, or NULL on error" name name
       );
       pr "\n";
+      (match deprecated_by with
+      | None -> ()
+      | Some alt ->
+        pr " * Deprecated: In new code, use guestfs_session_%s()
instead\n" alt
+      );
       pr " */\n";
 
       (* The function body *)
-- 
1.9.3

---
 generator/actions.ml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/generator/actions.ml b/generator/actions.ml
index 6b37712..2e0af55 100644
--- a/generator/actions.ml
+++ b/generator/actions.ml
@@ -2415,7 +2415,7 @@ the algorithm described in L<guestfs(3)/BLOCK DEVICE
NAMING>.
 
 =item C</dev/dm-N>
 
-Converted to C</dev/VG/LV> form using
C<guestfs_lvm_canonical_lvm_name>.
+Converted to C</dev/VG/LV> form using
C<guestfs_lvm_canonical_lv_name>.
 
 =back
 
@@ -11801,7 +11801,7 @@ to read data.
 
 The returned boolean tells you if there are any more journal
 records to read.  C<true> means you can read the next record
-(eg. using C<guestfs_journal_get_data>), and C<false> means you
+(eg. using C<guestfs_journal_get>), and C<false> means you
 have reached the end of the journal." };
 
   { defaults with
-- 
1.9.3

---
 generator/ocaml.ml | 15 ++++++++++++---
 1 file changed, 12 insertions(+), 3 deletions(-)

diff --git a/generator/ocaml.ml b/generator/ocaml.ml
index f8707ae..9284005 100644
--- a/generator/ocaml.ml
+++ b/generator/ocaml.ml
@@ -144,9 +144,14 @@ end
     fun ({ name = name; style = style; deprecated_by = deprecated_by;
           non_c_aliases = non_c_aliases;
           shortdesc = shortdesc } as f) ->
+      let need_doc = is_documented f in
+
+      if not need_doc then
+        pr "(**/**)\n";
+
       generate_ocaml_prototype name style;
 
-      if is_documented f then (
+      if need_doc then (
         pr "(** %s" shortdesc;
         (match deprecated_by with
          | None -> ()
@@ -155,14 +160,18 @@ end
         );
         pr " *)\n";
       );
-      pr "\n";
 
       (* Aliases. *)
       List.iter (
         fun alias ->
-          generate_ocaml_prototype alias style;
           pr "\n";
+          generate_ocaml_prototype alias style;
       ) non_c_aliases;
+
+      if not need_doc then
+        pr "(**/**)\n";
+
+      pr "\n";
   ) external_functions_sorted;
 
   pr "\
-- 
1.9.3

On Thu, Feb 12, 2015 at 03:18:28PM +0100, Pino Toscano
wrote:
> ---
>  generator/ocaml.ml | 15 ++++++++++++---
>  1 file changed, 12 insertions(+), 3 deletions(-)
> 
> diff --git a/generator/ocaml.ml b/generator/ocaml.ml
> index f8707ae..9284005 100644
> --- a/generator/ocaml.ml
> +++ b/generator/ocaml.ml
> @@ -144,9 +144,14 @@ end
>      fun ({ name = name; style = style; deprecated_by = deprecated_by;
>            non_c_aliases = non_c_aliases;
>            shortdesc = shortdesc } as f) ->
> +      let need_doc = is_documented f in
> +
> +      if not need_doc then
> +        pr "(**/**)\n";
> +
>        generate_ocaml_prototype name style;
>  
> -      if is_documented f then (
> +      if need_doc then (
>          pr "(** %s" shortdesc;
>          (match deprecated_by with
>           | None -> ()
> @@ -155,14 +160,18 @@ end
>          );
>          pr " *)\n";
>        );
> -      pr "\n";
>  
>        (* Aliases. *)
>        List.iter (
>          fun alias ->
> -          generate_ocaml_prototype alias style;
>            pr "\n";
> +          generate_ocaml_prototype alias style;
>        ) non_c_aliases;
> +
> +      if not need_doc then
> +        pr "(**/**)\n";
> +
> +      pr "\n";
>    ) external_functions_sorted;
>  
>    pr "\
> -- 
> 1.9.3
> 
> _______________________________________________
> Libguestfs mailing list
> Libguestfs@redhat.com
> https://www.redhat.com/mailman/listinfo/libguestfs
ACK series.

Rich.

-- 
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
Read my programming and virtualization blog: http://rwmj.wordpress.com
virt-df lists disk usage of guests without needing to install any
software inside the virtual machine.  Supports Linux and Windows.
http://people.redhat.com/~rjones/virt-df/

BTW this now provokes lots of (non-fatal) warnings like this:

./../src/session.c:26912: warning: guestfs_session_zgrepi is deprecated in the
inline comments, but no deprecation guards were found around the declaration.
(See the --deprecated-guards option for gtkdoc-scan.)

Rich.

-- 
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
Read my programming and virtualization blog: http://rwmj.wordpress.com
libguestfs lets you edit virtual machines.  Supports shell scripting,
bindings from many languages.  http://libguestfs.org