- 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 (
--
2.1.0
Richard W.M. Jones
2015-Oct-02 13:14 UTC
Re: [Libguestfs] [PATCH] ruby: improve rdoc markup
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
Apparently Analagous Threads
- [PATCH] Rust bindings: Implement Event features
- [PATCH 0/6] Update the way that API versions are generated for the man page.
- [PATCH 2/5] threads: Acquire and release the lock around each public guestfs_* API.
- Re: [PATCH] Rust bindings: Implement Event features
- [PATCH 1/4] ocaml: Add -Wno-missing-field-initializers to avoid a warning.