- 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 "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 _______________________________________________ Libguestfs mailing list [email protected] https://www.redhat.com/mailman/listinfo/libguestfs
