On Sep 25, 2018, at 10:18, Antoine Pitrou <solip...@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. Cheers, -Barry
signature.asc
Description: Message signed with OpenPGP
_______________________________________________ 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
