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... :-( * 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. 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
