On Tue, Sep 25, 2018 at 11:55 AM Barry Warsaw <ba...@python.org> wrote: > > On Sep 25, 2018, at 11:28, Victor Stinner <vstin...@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 _______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
