Libguestfs - Aug 2019 - Re: [PATCH 1/2] Rust bindings: Add long description

> 2019/08/13 1:01、Pino Toscano <ptoscano@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.

> :-)

On Tuesday, 13 August 2019 05:17:10 CEST Katsura Hiroyuki
wrote:
> 
> > 2019/08/13 1:01、Pino Toscano <ptoscano@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.
Can you explain which errors did you get? I tried pod2markdown on a
couple of API longdesc's, and the result seemed OK.
Most probably we will need to write our own pod2markdown though, as
pod2markdown does not allow users to customize all the options that
the Pod::Markdown module has.
> 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)
Considering we are generating most of the rust code using the
generator, IMHO it is better to produce the code directly following
the style conventions. I just checked the difference between our
currently generated guestfs.rs and the "formatted" version of it, and
fixing guestfs.rs does not seem too difficult. It can be done in steps,
of course, no need to rush everything in a single fix.

-- 
Pino Toscano

> Can you explain which errors did you get? I tried pod2markdown on a
> couple of API longdesc's, and the result seemed OK.
> Most probably we will need to write our own pod2markdown though, as
> pod2markdown does not allow users to customize all the options that
> the Pod::Markdown module has.
Yes. Most of the results seemed OK. But, for example, translating
'docs/guestfs-internals.pod' dumps the following errors at the end of
the
output file

```
# POD ERRORS

Hey! **The above document had some coding errors, which are explained
below:**

- Around line 17:

    Non-ASCII character seen before =encoding in
'┌───────────────────┐'.
Assuming UTF-8
```

I do not know whether there are such non-ascii characters in API longdescs,
and I have no idea to find
such characters easily. So, I am not able to say whether pod2markdown is
usable or not for now...

> IMHO it is better to produce the code directly following
> the style conventions.
OK. I'll send the formatting patch.

Regards,
Hiroyuki


2019年8月13日(火) 19:44 Pino Toscano <ptoscano@redhat.com>:
> On Tuesday, 13 August 2019 05:17:10 CEST Katsura Hiroyuki wrote:
> >
> > > 2019/08/13 1:01、Pino Toscano <ptoscano@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.
>
> Can you explain which errors did you get? I tried pod2markdown on a
> couple of API longdesc's, and the result seemed OK.
> Most probably we will need to write our own pod2markdown though, as
> pod2markdown does not allow users to customize all the options that
> the Pod::Markdown module has.
>
> > 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)
>
> Considering we are generating most of the rust code using the
> generator, IMHO it is better to produce the code directly following
> the style conventions. I just checked the difference between our
> currently generated guestfs.rs and the "formatted" version of it,
and
> fixing guestfs.rs does not seem too difficult. It can be done in steps,
> of course, no need to rush everything in a single fix.
>
> --
> Pino Toscano