re: kern/37427 document _ksem_* syscalls

[matthew green <mrg%eterna.com.au@localhost>]

The following reply was made to PR kern/37427; it has been noted by GNATS.

From: matthew green <mrg%eterna.com.au@localhost>
To: paul%whooppee.com@localhost
Cc: gnats-bugs%NetBSD.org@localhost, pgoyette%NetBSD.org@localhost, gnats-admin%netbsd.org@localhost,
    netbsd-bugs%netbsd.org@localhost, mmondor%pulsar-zone.net@localhost
Subject: re: kern/37427 document _ksem_* syscalls
Date: Sun, 29 Nov 2015 09:44:44 +1100

 > >>  We currently have man pages for sem(4) with cross-refs to several other
 > >>  pages for the specific functions.
 > >>
 > >>  Is there any reason why this is insufficient?  If this is OK, I will
 > >>  close the PR.
 > >
 > > is there documentation on the backend that is sufficient?  how is
 > > someone supposed to look at the sem(4) code without understanding
 > > the system calls that back it?
 > >
 > > i don't agree that "hidden" functionality should not be documented,
 > > and for actual system calls i don't believe that "in the sources"
 > > suffices.
 > 
 > Ah, so in addition to wanting the syscalls themselves documented
 > (which we have already), you want to see a ksem(9) man page 
 > describing the internal workings?
 > 
 > Let me see if I can do something here...  Step 1 - study code ...
 
 i don't need ksem(9) exactly -- that could be largely in the
 comments in the code.  i wouldn't object to it.
 
 it's the user/kernel boundary, even if largely hidden from users,
 deserves to be properly documented.  it might be documented as
 being a backend and point to the normal entry points that should
 be used instead.
 
 thanks!
 
 
 .mrg.