socket module documentation: confusing display of module functions vs class methods
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 77.2k
- Forks
- 36k
- PR merge metrics
- PR metrics pending
Description
socket, the module contains socket, the class. In the documentation, the functions of the module are rendered in exactly the same way as the methods of the class: socket.getaddrinfo and socket.accept look 'the same' in the documentation, even though the latter is actually socket.socket.accept. The only clue to that is the paragraph at the beginning of the section, but when e.g. linking to a particular method, that's easy to miss, and the user is left to infer that from the method description (or realise they have to scroll up/which section they're in).
The docs consistently use module.func for module-level functions and class.func for the methods of module.class. That style's fine most of the time and avoids the potential visual overload of always writing module.class.func. Naturally, the confusion arises only because the module and class have the same name in this particular case.
I'm not sure how to best resolve this, but I feel like the current situation is certainly not ideal.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the socket module documentation section linked in the issue, comparing the presentation of socket.getaddrinfo with socket.socket.accept. Determine a clearer way to distinguish module-level functions from class methods without changing the broader documentation style; done means readers can identify the owning object from the rendered documentation and direct links.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100