[Libguestfs] [PATCH 1/2] Rust bindings: Add long description
Katsura Hiroyuki
moratorium08 at gmail.com
Tue Aug 13 03:17:10 UTC 2019
> 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>
More information about the Libguestfs
mailing list