[Python-Dev] Documenting the private C API (was Re: Questions about signal handling.)

[Antoine Pitrou]

On Tue, 25 Sep 2018 10:01:56 -0400
Barry Warsaw <barry at python.org> wrote:
> On Sep 25, 2018, at 03:44, Victor Stinner <vstinner at redhat.com> wrote:
> 
> > By the way, recently, we had to fix yet another bug in signal
> > handling. A new function has been added:
> > 
> > void
> > _PyEval_SignalReceived(void)
> > {
> >    /* bpo-30703: Function called when the C signal handler of Python gets a
> >       signal. We cannot queue a callback using Py_AddPendingCall() since
> >       that function is not async-signal-safe. */
> >    SIGNAL_PENDING_CALLS();
> > }  
> 
> Is anybody else concerned about the proliferation of undocumented private C API functions?  I’m fine with adding leading underscore functions and macros when it makes sense, but what concerns me is that they don’t appear in the Python C API documentation (AFAICT).

Not really.  Many are just like "static" (i.e. module-private)
functions, except that they need to be shared by two or three different
C modules.  It's definitely the case for _PyEval_SignalReceived().

Putting them in the C API documentation risks making the docs harder to
browse through for third-party users.  I think it's enough if there's a
comment in the .h file explaining the given function.

Regards

Antoine.