> 2019/08/13 1:01、Pino Toscano <[email protected]>のメール: > > 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. > :-)
_______________________________________________ Libguestfs mailing list [email protected] https://www.redhat.com/mailman/listinfo/libguestfs
