[Libguestfs] [PATCH 1/2] Rust bindings: Add long description

[Pino Toscano]

On Sunday, 11 August 2019 06:42:21 CEST Hiroyuki Katsura wrote:
> `cargo doc` will generate docs with long descriptions.

This is a nice start, although most probably it will not look that good
though (since the plain text output may be misrendered as markdown).

I remember we talked about converting the POD texts to markdown, and
that there seems to be something we can use:
https://metacpan.org/release/Pod-Markdown
Did you try to use it?  What were the results?

> I did not add the settings of outputting these docs to `/website`.
> This is because
>  - by publishing this crate to crates.io, users can see the docs in
>  `docs.rs` like `https://docs.rs/guestfs/<version>/guestfs/`. It is easy
>  to hold multiple documents corresponding to each version.
>  - the style of the documents generated by `cargo doc` is far different
>  from the documents which already exist.

While this certainly makes sense, note that we don't create in the
website online API docs, at most just basic intro pages for the various
programming languages for which we have (stable) bindings.  For example
http://libguestfs.org/guestfs-ocaml.3.html

(IMHO we could publish API docs for the few bindings that have them,
but that is a separate discussion and for another day.)

I'd leave the paragraph above out from the commit message, since it is
mostly unrelated.

> ---
>  generator/rust.ml | 10 ++++++++++
>  1 file changed, 10 insertions(+)
> 
> diff --git a/generator/rust.ml b/generator/rust.ml
> index 1f5cefa62..3a07c3b53 100644
> --- a/generator/rust.ml
> +++ b/generator/rust.ml
> @@ -52,6 +52,14 @@ let translate_bad_symbols s =
>    else
>      s
>  
> +(* output longdesc to the rust file *)
> +let pr_longdesc name longdesc indent_depth =

indent_depth seems always 1, so I'd say to hardcode this indentation
level for now (it can be always changed).

> +  let l = pod2text name longdesc in

Better specify a width, so indent + comment + text does not overflow
the recommended line limit of 100 characters:
https://rust-lang.github.io/rustc-guide/conventions.html#line-length

> +  List.iter (fun x ->
> +      indent indent_depth;
> +      pr "/// %s\n" x;
> +    ) l

Without indent_depth, this can be nicely simplified as

  List.iter (pr "    /// %s\n") l

:-)

-- 
Pino Toscano
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: This is a digitally signed message part.
URL: <http://listman.redhat.com/archives/libguestfs/attachments/20190812/4b2d835d/attachment.sig>