On Fri, Oct 02, 2015 at 02:53:30PM +0200, Pino Toscano wrote:
- fix the syntax of hyperlinks - replace the deprecation text with a simplier named list item, so it's more visible - use a named list item for the pointer to the C documentation of each API - add a named list item for the version of each API --- generator/ruby.ml | 27 ++++++++++++++++----------- 1 file changed, 16 insertions(+), 11 deletions(-)
diff --git a/generator/ruby.ml b/generator/ruby.ml index cd6678d..87bb34a 100644 --- a/generator/ruby.ml +++ b/generator/ruby.ml @@ -178,7 +178,7 @@ parse_flags (int argc, VALUE *argv) * Guestfs::Guestfs.new([{:environment => false, :close_on_exit => false}]) -> Guestfs::Guestfs * * Call - * +guestfs_create_flags+[http://libguestfs.org/guestfs.3.html#guestfs_create_flags] + * {guestfs_create_flags}[http://libguestfs.org/guestfs.3.html#guestfs_create_flags] * to create a new libguestfs handle. The handle is represented in * Ruby as an instance of the Guestfs::Guestfs class. */ @@ -235,7 +235,7 @@ ruby_guestfs_create (int argc, VALUE *argv, VALUE module) * g.close() -> nil * * Call - * +guestfs_close+[http://libguestfs.org/guestfs.3.html#guestfs_close] + * {guestfs_close}[http://libguestfs.org/guestfs.3.html#guestfs_close] * to close the libguestfs handle. */ static VALUE @@ -258,7 +258,7 @@ ruby_guestfs_close (VALUE gv) * g.set_event_callback(cb, event_bitmask) -> event_handle * * Call - * +guestfs_set_event_callback+[http://libguestfs.org/guestfs.3.html#guestfs_set_event_callback] + * {guestfs_set_event_callback}[http://libguestfs.org/guestfs.3.html#guestfs_set_event_callback] * to register an event callback. This returns an event handle. */ static VALUE @@ -297,7 +297,7 @@ ruby_set_event_callback (VALUE gv, VALUE cbv, VALUE event_bitmaskv) * g.delete_event_callback(event_handle) -> nil * * Call - * +guestfs_delete_event_callback+[http://libguestfs.org/guestfs.3.html#guestfs_delete_event_callback] + * {guestfs_delete_event_callback}[http://libguestfs.org/guestfs.3.html#guestfs_delete_event_callback] * to delete an event callback. */ static VALUE @@ -328,7 +328,7 @@ ruby_delete_event_callback (VALUE gv, VALUE event_handlev) * Guestfs::Guestfs.event_to_string(events) -> string * * Call - * +guestfs_event_to_string+[http://libguestfs.org/guestfs.3.html#guestfs_event_to_string] + * {guestfs_event_to_string}[http://libguestfs.org/guestfs.3.html#guestfs_event_to_string] * to convert an event or event bitmask into a printable string. */ static VALUE @@ -477,13 +477,18 @@ get_all_event_callbacks (guestfs_h *g, size_t *len_rtn) 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 = String.concat "\n * " doc in let doc = trim doc in + let doc = + match version_added f with + | None -> doc + | Some version -> doc ^ (sprintf "\n *\n * [Since] Added in version %s." version) in + let doc = + match f with + | { deprecated_by = None } -> doc + | { deprecated_by = Some alt } -> + doc ^ (sprintf "\n *\n * [Deprecated] In new code, use rdoc-ref:%s instead." alt) in
(* Because Ruby documentation appears as C comments, we must * replace any instance of "/*". @@ -518,8 +523,8 @@ get_all_event_callbacks (guestfs_h *g, size_t *len_rtn) * * %s * - * (For the C API documentation for this function, see - * +guestfs_%s+[http://libguestfs.org/guestfs.3.html#guestfs_%s]). + * [C API] For the C API documentation for this function, see + * {guestfs_%s}[http://libguestfs.org/guestfs.3.html#guestfs_%s]. */ " f.name args ret f.shortdesc doc f.name f.name ) else (
ACK. I wonder if Ruby changed the format of rdoc? Could swear this worked when I first wrote it. Thanks, Rich. -- Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones Read my programming and virtualization blog: http://rwmj.wordpress.com virt-top is 'top' for virtual machines. Tiny program with many powerful monitoring features, net stats, disk stats, logging, etc. http://people.redhat.com/~rjones/virt-top