Libguestfs - May 2015 - [PATCH 4/4] java: doc: add the version (if available) of APIs

This way the version string of each API can be used also in other
generator modules.

Mostly code motion, no actual behaviour changes.
---
 generator/c.ml          | 21 ++++++++++-----------
 generator/docstrings.ml |  6 ++++++
 2 files changed, 16 insertions(+), 11 deletions(-)

diff --git a/generator/c.ml b/generator/c.ml
index 63dc09a..a2b9c94 100644
--- a/generator/c.ml
+++ b/generator/c.ml
@@ -301,8 +301,10 @@ 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";
-  let version = api_version f.added in
-  pr "(Added in %s)\n\n" version;
+  (match version_added f with
+  | Some version -> pr "(Added in %s)\n\n" version
+  | None -> assert false
+  );
 
   (* Handling of optional argument variants. *)
   if optargs <> [] then (
@@ -322,8 +324,8 @@ L</KEYS AND PASSPHRASES> for more
information.\n\n";
     pr "See L</CALLS WITH OPTIONAL ARGUMENTS>.\n\n";
   )
 
-and generate_actions_pod_back_compat_entry { name = name; added = added;
-                                             style = ret, args, _ } +and
generate_actions_pod_back_compat_entry ({ name = name;
+                                              style = ret, args, _ } as f)   
pr "=head2 guestfs_%s\n\n" name;
   generate_prototype ~extern:false ~indent:" " ~handle:"g"
     ~prefix:"guestfs_" name (ret, args, []);
@@ -334,13 +336,10 @@ and generate_actions_pod_back_compat_entry { name = name;
added = added;
   pr "L</guestfs_%s_opts> with no optional arguments.\n" name;
   pr "\n";
 
-  let version = api_version added in
-  pr "(Added in %s)\n\n\n" version;
-
-and api_version = function
-  | (0, 0, release) -> sprintf "0.%d" release
-  | ((0|1) as major, minor, release) -> sprintf "%d.%d.%d" major
minor release
-  | _ -> assert false
+  (match version_added f with
+  | Some version -> pr "(Added in %s)\n\n\n" version
+  | None -> assert false
+  )
 
 and generate_structs_pod ()    generate_header PODStyle GPLv2plus;
diff --git a/generator/docstrings.ml b/generator/docstrings.ml
index 8ca54d1..caf836c 100644
--- a/generator/docstrings.ml
+++ b/generator/docstrings.ml
@@ -51,6 +51,12 @@ fact that they are deprecated indicates that there are
problems
 with correct use of these functions." prefix alt in
     Some txt
 
+let version_added = function
+  | { added = (0, 0, release) } -> Some (sprintf "0.%d" release)
+  | { added = ((0|1) as major, minor, release) } ->
+    Some (sprintf "%d.%d.%d" major minor release)
+  | _ -> None
+
 let copyright_years    let this_year = 1900 + (localtime (time ())).tm_year in
   if this_year > 2009 then sprintf "2009-%04d" this_year else
"2009"
-- 
2.1.0

---
 generator/gobject.ml | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/generator/gobject.ml b/generator/gobject.ml
index e563610..8d5ac06 100644
--- a/generator/gobject.ml
+++ b/generator/gobject.ml
@@ -1109,6 +1109,10 @@ guestfs_session_close (GuestfsSession *session, GError
**err)
       | Some alt ->
         pr " * Deprecated: In new code, use guestfs_session_%s()
instead\n" alt
       );
+      (match version_added f with
+      | None -> ()
+      | Some version -> pr " * Since: %s\n" version
+      );
       pr " */\n";
 
       (* The function body *)
-- 
2.1.0

Make sure to not add more newline's than needed.
---
 generator/ocaml.ml | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/generator/ocaml.ml b/generator/ocaml.ml
index e7c6a1a..d2a4690 100644
--- a/generator/ocaml.ml
+++ b/generator/ocaml.ml
@@ -153,12 +153,23 @@ end
       generate_ocaml_prototype name style;
 
       if need_doc then (
+        let has_tags = ref false in
+
         pr "(** %s" shortdesc;
         (match deprecated_by with
          | None -> ()
          | Some replacement ->
-             pr "\n\n    @deprecated Use {!%s} instead\n" replacement
+             has_tags := true;
+             pr "\n\n    @deprecated Use {!%s} instead" replacement
+        );
+        (match version_added f with
+        | None -> ()
+        | Some version ->
+             has_tags := true;
+             pr "\n\n    @since %s" version
         );
+        if !has_tags then
+          pr "\n";
         pr " *)\n";
       );
 
-- 
2.1.0

---
 generator/java.ml | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/generator/java.ml b/generator/java.ml
index 573f1c2..4c89197 100644
--- a/generator/java.ml
+++ b/generator/java.ml
@@ -273,6 +273,10 @@ public class GuestFS {
         pr "   * </p><p>\n";
         pr "   * %s\n" doc;
         pr "   * </p>\n";
+        (match version_added f with
+        | None -> ()
+        | Some version -> pr "   * @since %s\n" version
+        );
         (match f with
         | { deprecated_by = None } -> ()
         | { deprecated_by = Some alt } ->
-- 
2.1.0

On Thu, May 28, 2015 at 04:47:55PM +0200, Pino Toscano
wrote:
> ---
>  generator/java.ml | 4 ++++
>  1 file changed, 4 insertions(+)
> 
> diff --git a/generator/java.ml b/generator/java.ml
> index 573f1c2..4c89197 100644
> --- a/generator/java.ml
> +++ b/generator/java.ml
> @@ -273,6 +273,10 @@ public class GuestFS {
>          pr "   * </p><p>\n";
>          pr "   * %s\n" doc;
>          pr "   * </p>\n";
> +        (match version_added f with
> +        | None -> ()
> +        | Some version -> pr "   * @since %s\n" version
> +        );
>          (match f with
>          | { deprecated_by = None } -> ()
>          | { deprecated_by = Some alt } ->
ACK series.

Thanks,

Rich.

-- 
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
Read my programming and virtualization blog: http://rwmj.wordpress.com
virt-p2v converts physical machines to virtual machines.  Boot with a
live CD or over the network (PXE) and turn machines into KVM guests.
http://libguestfs.org/virt-v2v