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

[Yury Selivanov]

On Tue, Sep 25, 2018 at 11:55 AM Barry Warsaw <barry at python.org> wrote:
>
> On Sep 25, 2018, at 11:28, Victor Stinner <vstinner at redhat.com> wrote:
> >
> > But if we have a separated documented for CPython internals, why not
> > documenting private functions. At least, I would prefer to not put it
> > at the same place an the *public* C API. (At least, a different
> > directory.)
>
> I like the idea of an “internals” C API documentation, separate from the public API.

For that we can just document them in the code, right?  Like this one,
from Include/internal/pystate.h:

/* Initialize _PyRuntimeState.
   Return NULL on success, or return an error message on failure. */
PyAPI_FUNC(_PyInitError) _PyRuntime_Initialize(void);

My main concern with maintaining a *separate* documentation of
internals is that it would make it harder to keep it in sync with the
actual implementation.  We often struggle to keep the comments in the
code in sync with that code.

Yury