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

Yury Selivanov yselivanov.ml at gmail.com
Tue Sep 25 12:09:33 EDT 2018

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

More information about the Python-Dev mailing list