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

[Katsura Hiroyuki]

> 2019/08/13 1:01、Pino Toscano <ptoscano at redhat.com>のメール:
> 
> 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 <https://metacpan.org/release/Pod-Markdown>
> Did you try to use it?  What were the results?

Yes. As I mentioned before, it looked pretty good except for some encode-errors.
However, at first, I just translate pod to text by the exisiting function because using 
pod2markdown looks a little tricky.

> 
>> I did not add the settings of outputting these docs to `/website`.
>> This is because
>> - by publishing this crate to crates.io <http://crates.io/>, users can see the docs in
>> `docs.rs <http://docs.rs/>` like `https://docs.rs/guestfs/<version>/guestfs/` <https://docs.rs/guestfs/%3Cversion%3E/guestfs/%60>. 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 <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.
> 

Hmm, It seems better to create an intro page for rust bindings. 
I’ll create it.

>> ---
>> 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).

OK. 

> 
>> +  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 <https://rust-lang.github.io/rustc-guide/conventions.html#line-length>

Ah, It seems good. 

Question: 
There are some places where the length of the line in the generated code
is over 100 characters. Of course, I can try to make the length of each line under 100 
characters. However, there is a nice tool: ‘rustfmt.’ I want to use this as a ‘post-process’ 
of generating bindings. Is it OK?(I should have ask you when I sent the first patch)

> 
>> +  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
> 

Hmm, that’s true.


> :-)

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/libguestfs/attachments/20190813/f5e0fabe/attachment.htm>