Document Lwt_io.printf flushing behavior #544
Conversation
src/unix/lwt_io.mli
Outdated
| val fprintf : output_channel -> ('a, unit, string, unit Lwt.t) format4 -> 'a | ||
| (* %! does nothing here. To flush the channel, use Lwt_io.(flush channel) *) |
There was a problem hiding this comment.
Hey, just in case: to make this an ocamldoc comment, it should be:
(** [%!] does nothing here. To flush the channel, use [Lwt_io.flush channel]. *)
The (** makes ocamldoc pick it up (so it is included in the generated manual), and the [...] is the ocamldoc source code style. I also took the liberty of not opening Lwt_io in channel, because that is likely to be a user's identifier, rather than something from Lwt_io when someone is using fprintf. But for print*f and eprint*f, it should probably be with Lwt_io as you have it, and Lwt_io.stdout and Lwt_io.stderr, respectively, rather than a user's identifier "channel".
There was a problem hiding this comment.
Sorry, but I'm not sure what you mean by "not opening Lwt_io in channel".
There was a problem hiding this comment.
Oh, the Lwt_io.(foo bar) syntax is a "local open," it brings the identifiers of Lwt_io in scope for both foo and bar.
So, for stdout, we probably want something like Lwt_io.(flush stdout), because that means "take both flush and stdout potentially from Lwt_io (or anything else that is in scope)."
But for a user's custom channel, Lwt_io.flush channel, because only flush here would come from Lwt_io.
There was a problem hiding this comment.
Ah, sorry; I just saw this comment. Thanks for the explanation.
I addressed this in 5cd987d. Does it look okay?
In f103d78, I linked to Lwt_io.flush for the fprint*f docs. I tried to do the same for print*f and eprint*f, but I couldn't find a way to link to the identifiers flush and stdout in docs of the form Lwt_io.(flush stdout). Am I missing something?
There was a problem hiding this comment.
Thank you, it looks good now :) For the cross-reference links, I'd say just not to use them, because, as you can see, the support for including cross-references inside expressions is lacking, and you have to manually try to guess where to insert spaces around and inside [...], etc. It's difficult for most people to predict how that will be displayed, and it makes the .mli file hard to read.
The rule I use for myself is:
- If it's a single identifier on its own, try to get it cross-referenced with
{!...}. - If it's a non-trivial expression like
Lwt_io.flush foo, don't try to get anything inside it cross-referenced, and just write it verbatim.
So, my suggestion is to omit f103d78.
|
Thank you! |
|
My pleasure! Thanks for the comments. |
As described in #455.