Hi Ted,
Ted Bullock wrote on Mon, Jan 16, 2023 at 12:56:06PM -0700:
> The impetus is that the event(3) manual page isn't all that good for
> documenting how to use the library and it is missing functions that are
> included in the API and available in the shared library.
That seems true, and those are good reasons to improve the manual pages.
> Upstream of course has moved on to version 2.x, as far as I can tell
> there is no more maintenance being done on the 1.4 version
According to
https://github.com/libevent/libevent/tree/patches-1.4
that seems accurate to me: it appears the 1.4 branch was last touched
in the git repo eight years ago, and it is marked "stale",
along with the 2.0 and 2.1 branches.
> that OpenBSD ships except the work that is done internally in the OS.
Given that our event.3 says
.\" Copyright (c) 2000 Artur Grabowski
and that the libevent git repo contains a Jurassic version
of our event.3 in the 1.4 branch and does no longer appear
to contain *any* kind of documentation in the master branch -
in particular, there is no event.3 in the master branch any longer -
i think maintaining the libevent manual pages ourselves is perfectly
fine. I see no danger that any documentation might need to be merged
from the libevent git: it appears the libevent project regards
documentation as a useless distraction at best... :-o
> Anyway, here is what I came up with for a few functions after reading
> the source tree. I also went back through historical releases to see
> how the API evolved over time.
I think this is likely a worthwhile project, but still needs a lot
of work before it can be considered for commit.
> I'm planning to finish off documenting the rest of the library, if
> folks have feedback, I'm interested.
Given how much feedback i have on your first file, i'm not yet reading
your second and third file right now.
We do development in steps, and the tree needs to build and be better
after each commit than before that commit. So to be able to be committed,
your patch for the first file should also delete the now redundant
information from event.3. Regard it as splitting one well-defined
part out of the excessively large event.3 and adding lots of missing
information while splitting it out.
> event_init.3
>
At this point, one line is missing:
.\" $OpenBSD$
The command `mandoc -T lint` tells you:
mandoc: event_init.3: STYLE: RCS id missing: (OpenBSD)
> .\" Copyright (c) 2023 Ted Bullock
> .\"
> .\" Permission to use, copy, modify, and distribute this software for any
> .\" purpose with or without fee is hereby granted, provided that the above
> .\" copyright notice and this permission notice appear in all copies.
> .\"
> .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
> .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
> .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
> .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
> .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
> .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
> .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
> .\"
> .Dd $Mdocdate: January 9 2023 $
> .Dt EVENT_INIT 3
> .Os
> .Sh NAME
> .Nm event_base_new ,
> .Nm event_init
This is not nice.
Unless there is a good reason to name the page after a function that
is not the first function in the NAME section, put the function
corresponding to the file name first in NAME and in all other sections.
> .Nd initializes an
> .Vt event_base
> instance
While nesting markup inside .Nd is technically possible,
it is fragile, looks ugly, and we certainly don't do it in OpenBSD.
> .Sh SYNOPSIS
> .In event.h
> .Ft "struct event_base *"
> .Fn event_base_new void
> .Ft "struct event_base *"
> .Fn event_init void
> .Sh DESCRIPTION
> The functions
> .Fn event_base_new
> and
> .Fn event_init
> initialize the
> .Lb libevent
We don't normally use the .Lb macro in OpenBSD.
Maybe just talk about "the event library" with no markup?
The existing event.3 talks about
The
.Nm event
API ...
which is not wrong, but i'm not convinced the .Nm markup provides much
value here.
> and need to be called prior to scheduling an event or
> starting the event-loop. The two functions are similar, although global
> variables are set when calling
> .Fn event_init
> to help simplify the API for programs requiring only one event-loop.
This is not good. Don't start comparing functions without precisely
saying first what each function actually does, in particular not in the
first sentence of a manual page.
Instead, the first sentence should only state the general purpose of
the functions documented in the page. In this page, it might not be
needed at all, you could probably start with event_base_new(3) right
away.
After the introductory sentence(s), if any, start with one function and
document it thoroughly.
