devguide
devguide copied to clipboard
dev task of documenting undocumented APIs
Moved from https://github.com/python/cpython/issues/55174
Just so we don't have to go to the bugtracker to remind ourselves of what this is about, here's a recap:
Once the docs are built using Python 3, then the coverage results can be used by people wanting to contribute as something to do. Should also mention in the task that some APIs should probably be private: http://mail.python.org/pipermail/python-dev/2010-November/105476.html
The issue is still valid and waiting for someone to submit a patch to the devguide.
- provide developers guidance on how to document undocumented APIs
- when and how to use
__all__
- include rules from the linked email
- highlight "do no harm" to existing users as discussed in email
I'm going to go ahead and close this issue. Please reopen if you wish.
Was this closed because it was resolved, or closed because it is not needed anymore?
Michael's mail has been superseded by PEP-387.
As for documenting undocumented APIs, AFAIK we could use the same process as for recent “linting”-style tasks. Here's a draft of concrete next steps:
- [ ] Make the docs coverage build work
- [ ] Add a list of current undocumented API, and make CI warn/fail if it finds undocumented API that's not in the list
- [ ] Work to document API or mark known false positives
Do I understand the issue correctly? If so it should probably go back to the cpython repo.