Libguestfs - Feb 2015 - [PATCH 3/3] java: add @Deprecated annotation for deprecated methods

---
 generator/utils.ml  | 8 +++++++-
 generator/utils.mli | 3 +++
 2 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/generator/utils.ml b/generator/utils.ml
index b24ba8c..3a62084 100644
--- a/generator/utils.ml
+++ b/generator/utils.ml
@@ -360,4 +360,10 @@ let args_of_optargs optargs      | OInt64 n -> Int64 n
     | OString n -> String n
     | OStringList n -> StringList n
-  ) optargs;
+  ) optargs
+
+let html_escape text +  let text = replace_str text "&"
"&" in
+  let text = replace_str text "<" "&lt;" in
+  let text = replace_str text ">" "&gt;" in
+  text
diff --git a/generator/utils.mli b/generator/utils.mli
index 5fd40ce..e0f30c3 100644
--- a/generator/utils.mli
+++ b/generator/utils.mli
@@ -131,3 +131,6 @@ val spaces : int -> string
 
 val args_of_optargs : Types.optargs -> Types.args
 (** Convert a list of optargs into an equivalent list of args *)
+
+val html_escape : string -> string
+(** Escape a text for HTML display. *)
-- 
1.9.3

- use <p>..</p> for text paragraphs, instead of just using <p>
to
  separate them
- slightly improve the metadata in eventToString and set_event_callback
- fix the textual @see in set_event_callback, so it is accepted also in
  JDK 8
- escape the doc text, so &, <, and > will not be considered as HTML
  tags but actual text
- use the @deprecated tag instead of adding the customary deprecation
  note to the doc text
---
 generator/java.ml | 55 ++++++++++++++++++++++++++++++++++++-------------------
 1 file changed, 36 insertions(+), 19 deletions(-)

diff --git a/generator/java.ml b/generator/java.ml
index 35af653..8b0d12f 100644
--- a/generator/java.ml
+++ b/generator/java.ml
@@ -41,19 +41,21 @@ import java.util.HashMap;
 import java.util.Map;
 
 /**
- * Libguestfs handle.
  * <p>
+ * Libguestfs handle.
+ * </p><p>
  * The <code>GuestFS</code> object corresponds to a libguestfs
handle.
- * <p>
+ * </p><p>
  * Note that the main documentation for the libguestfs API is in
  * the following man pages:
- * <p>
+ * </p><p>
  * <ol>
  * <li> <a
href=\"http://libguestfs.org/guestfs-java.3.html\"><code>guestfs-java(3)</code></a>
and </li>
  * <li> <a
href=\"http://libguestfs.org/guestfs.3.html\"><code>guestfs(3)</code></a>.
</li>
  * </ol>
- * <p>
+ * </p><p>
  * This javadoc is <b>not</b> a good introduction to using
libguestfs.
+ * </p>
  *
  * @author rjones
  */
@@ -109,13 +111,15 @@ public class GuestFS {
   private native long _create (int flags) throws LibGuestFSException;
 
   /**
+   * <p>
    * Close a libguestfs handle.
-   *
+   * </p><p>
    * You can also leave handles to be collected by the garbage
    * collector, but this method ensures that the resources used
    * by the handle are freed up immediately.  If you call any
    * other methods after closing the handle, you will get an
    * exception.
+   * </p>
    *
    * @throws LibGuestFSException
    */
@@ -152,7 +156,12 @@ public class GuestFS {
   pr "\n";
 
   pr "\
-  /** Utility function to turn an event number or bitmask into a string. */
+  /**
+   * Utility function to turn an event number or bitmask into a string.
+   *
+   * @param events the event number to convert
+   * @return text representation of event
+   */
   public static String eventToString (long events)
   {
     return _event_to_string (events);
@@ -161,13 +170,14 @@ public class GuestFS {
   private static native String _event_to_string (long events);
 
   /**
-   * Set an event handler.
    * <p>
+   * Set an event handler.
+   * </p><p>
    * Set an event handler (<code>callback</code>) which is called
when any
    * event from the set (<code>events</code>) is raised by the API.
    * <code>events</code> is one or more
<code>EVENT_*</code> constants,
    * bitwise ORed together.
-   * <p>
+   * </p><p>
    * When an event happens, the callback object's
<code>event</code> method
    * is invoked like this:
    * <pre>
@@ -180,14 +190,16 @@ public class GuestFS {
    * Note that you can pass arbitrary data from the main program to the
    * callback by putting it into your {@link EventCallback callback object},
    * then accessing it in the callback via <code>this</code>.
-   * <p>
+   * </p><p>
    * This function returns an event handle which may be used to delete
    * the event.  Note that event handlers are deleted automatically when
    * the libguestfs handle is closed.
+   * </p>
    *
    * @throws LibGuestFSException
-   * @see The section \"EVENTS\" in the guestfs(3) manual
+   * @see \"The section &quot;EVENTS&quot; in the guestfs(3)
manual\"
    * @see #delete_event_callback
+   * @return handle for the event
    */
   public int set_event_callback (EventCallback callback, long events)
     throws LibGuestFSException
@@ -203,14 +215,16 @@ public class GuestFS {
     throws LibGuestFSException;
 
   /**
-   * Delete an event handler.
    * <p>
+   * Delete an event handler.
+   * </p><p>
    * Delete a previously registered event handler.  The 'eh' parameter
is
    * the event handle returned from a previous call to
    * {@link #set_event_callback set_event_callback}.
-   * <p>
+   * </p><p>
    * Note that event handlers are deleted automatically when the
    * libguestfs handle is closed.
+   * </p>
    *
    * @throws LibGuestFSException
    * @see #set_event_callback
@@ -243,22 +257,25 @@ public class GuestFS {
           if f.protocol_limit_warning then
             doc ^ "\n\n" ^ protocol_limit_warning
           else doc in
-        let doc -          match deprecation_notice f with
-          | None -> doc
-          | Some txt -> doc ^ "\n\n" ^ txt in
         let doc = pod2text ~width:60 f.name doc in
         let doc = List.map (		(* RHBZ#501883 *)
           function
-          | "" -> "<p>"
-          | nonempty -> nonempty
+          | "" -> "</p><p>"
+          | nonempty -> html_escape nonempty
         ) doc in
         let doc = String.concat "\n   * " doc in
 
         pr "  /**\n";
-        pr "   * %s\n" f.shortdesc;
         pr "   * <p>\n";
+        pr "   * %s\n" f.shortdesc;
+        pr "   * </p><p>\n";
         pr "   * %s\n" doc;
+        pr "   * </p>\n";
+        (match f with
+        | { deprecated_by = None } -> ()
+        | { deprecated_by = Some alt } ->
+          pr "   * @deprecated In new code, use {@link #%s}
instead\n" alt
+        );
         pr "   * @throws LibGuestFSException\n";
         pr "   */\n";
       );
-- 
1.9.3

---
 generator/java.ml | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/generator/java.ml b/generator/java.ml
index 8b0d12f..81faff1 100644
--- a/generator/java.ml
+++ b/generator/java.ml
@@ -280,7 +280,11 @@ public class GuestFS {
         pr "   */\n";
       );
       pr "  ";
-      generate_java_prototype ~public:true ~semicolon:false f.name f.style;
+      let deprecated +        match f with
+        | { deprecated_by = None } -> false
+        | { deprecated_by = Some _ } -> true in
+      generate_java_prototype ~public:true ~semicolon:false ~deprecated f.name
f.style;
       pr "\n";
       pr "  {\n";
       pr "    if (g == 0)\n";
@@ -421,7 +425,8 @@ and generate_java_call_args ~handle (_, args, optargs)    pr
")"
 
 and generate_java_prototype ?(public=false) ?(privat=false) ?(native=false)
-    ?(semicolon=true) name (ret, args, optargs) +    ?(semicolon=true)
?(deprecated=false) name (ret, args, optargs) +  if deprecated then pr
"@Deprecated ";
   if privat then pr "private ";
   if public then pr "public ";
   if native then pr "native ";
-- 
1.9.3

On Tue, Feb 10, 2015 at 03:12:26PM +0100, Pino Toscano
wrote:
> ---
>  generator/java.ml | 9 +++++++--
>  1 file changed, 7 insertions(+), 2 deletions(-)
> 
> diff --git a/generator/java.ml b/generator/java.ml
> index 8b0d12f..81faff1 100644
> --- a/generator/java.ml
> +++ b/generator/java.ml
> @@ -280,7 +280,11 @@ public class GuestFS {
>          pr "   */\n";
>        );
>        pr "  ";
> -      generate_java_prototype ~public:true ~semicolon:false f.name
f.style;
> +      let deprecated > +        match f with
> +        | { deprecated_by = None } -> false
> +        | { deprecated_by = Some _ } -> true in
> +      generate_java_prototype ~public:true ~semicolon:false ~deprecated
f.name f.style;
>        pr "\n";
>        pr "  {\n";
>        pr "    if (g == 0)\n";
> @@ -421,7 +425,8 @@ and generate_java_call_args ~handle (_, args, optargs)
>    pr ")"
>  
>  and generate_java_prototype ?(public=false) ?(privat=false)
?(native=false)
> -    ?(semicolon=true) name (ret, args, optargs) > +   
?(semicolon=true) ?(deprecated=false) name (ret, args, optargs) > +  if
deprecated then pr "@Deprecated ";
>    if privat then pr "private ";
>    if public then pr "public ";
>    if native then pr "native ";
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/