[Python-Dev] Documenting the private C API (was Re: Questions about signal handling.)
On Sep 25, 2018, at 10:18, Antoine Pitrou <solipsis at pitrou.net> wrote:
> 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().
Purely static functions which appear only in the file they are defined in are probably fine not to document, although I do still think we should take care to comment on their semantics and external behaviors (i.e. reference counting). But if they?re used in multiple C files, then I think they *can* deserve placement within the documentation.
> 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.
-------------- next part --------------
A non-text attachment was scrubbed...
Size: 833 bytes
Desc: Message signed with OpenPGP