8:12 a.m.
- 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&...
and </li>
* <li> <a
href=\"http://libguestfs.org/guestfs.3.html\"><code>gu...;.
</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 "EVENTS" 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