On Fri, Aug 04, 2017 at 07:53:19PM +0200, Ingo Schwarze wrote: > Hi Rob, > > thanks for looking at libevent documentation. It is in dire need > of improvements in multiple respects. > > Rob Pierce wrote on Fri, Aug 04, 2017 at 10:21:16AM -0400: > > > As of the last commit to src/lib/libevent/log.c the library > > no longer prints to stderr. Update man page accordingly. > > > > Ok? > > But honestly, i'm not convinced that this patch is right. > > Look at event.c. EVENT_SHOW_METHOD is still inspected (line 154), > and if it is set, the library does issue a message. > > But looking at the code and at the documentation, i instantly > see lots and lots of issues that need fixing. Unsorted: > > * EVENT_SHOW_METHOD ought to be documented in the ENVIRONMENT > section. The section name "ADDITIONAL NOTES" is bogus. > > * If you document an ENVIRONMENT variable, you should also say > which value(s) it is supposed to have (in this case, the value > is ignored, and even an empty value counts as "set", which is > not at all obvious). > > * The information is missing that that the variable is ignored > in setuid and setgid programs as defined by issetugid(2). > > * Talking about "displaying" something is useless in library > documentation. You also have to explain where the message > will appear. Certainly not on stdout, right? > > * In this case, the message won't appear anywhere at all by default, > not even in the system logs. > > * To make *any* messages from libevent appear anywhere at all, > the application program has to supply a logging callback > function using the public interface function > event_set_log_callback(3). Unfortunately, man -k tells me > that function isn't documented anywhere at all. > A classic case of user-level RTFS... :-(
... and there it is! Thanks Ingo. I didn't go deep enough. > * Don't you dare add yet more functions to event(3). > It is already of excessive size and conflating documentation for > classes of functions almost unrelated to each other - like, > what's the point of having signal_set(3) and bufferevent_read(3) > in the same manual page? > > I dimly remeber that somebody tried and started to clean this mess > up some years ago, but wasn't persistent enough to go anywhere with > it. If you want to look at that and don't find it instantly, i can > dig it up for you. Or you can simply start from scratch, the old > discussion didn't go so far that much would be lost starting over. > > If you want to tackle this, expect several days of work, > involving much reading of code. I will put it on my list! Regards, Rob > Yours, > Ingo > > > > Index: event.3 > > =================================================================== > > RCS file: /cvs/src/lib/libevent/event.3,v > > retrieving revision 1.53 > > diff -u -p -r1.53 event.3 > > --- event.3 29 Jun 2017 01:25:59 -0000 1.53 > > +++ event.3 4 Aug 2017 14:08:44 -0000 > > @@ -517,10 +517,6 @@ by setting the environment variable > > or > > .Va EVENT_NOSELECT , > > respectively. > > -By setting the environment variable > > -.Va EVENT_SHOW_METHOD , > > -.Nm libevent > > -displays the kernel notification method that it uses. > > .Sh RETURN VALUES > > Upon successful completion > > .Fn event_add
