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

[Eric Snow]

On Tue, Sep 25, 2018 at 8:30 AM Barry Warsaw <barry at python.org> wrote:
> On Sep 25, 2018, at 10:18, Antoine Pitrou <solipsis at pitrou.net> wrote:
> > 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.
>
> It’s a trade-off for sure.  I don’t have any great ideas about how to balance that, and I don’t know what documentation techniques would help, but it does often bother me that I can’t search for them on docs.python.org.

FWIW, I've run into the same issue.  Perhaps we could have a single
dedicated page in the C-API docs for internal API.  It could be just a
big table with a bold red warning at the top (e.g. "These are
internal-only APIs, here for the benefit of folks working on CPython
itself.").  We *could* even have a CI check to ensure that new
internal API (which doesn't happen often) gets added to the table.

-eric