os.walk docstring differs from its rst docs

[lheckemann]

Documentation

os.walk's docstring is largely similar, but has minor differences from its RST docs. I think it would be good to either have the two descriptions be intentionally completely different (because they serve different purposes), or ensure consistency between them so that improvements to one don't go missing in the other. The following ideas come to mind:

• Replace os.walk's docstring with a short summary that goes into less detail and won't need to be kept in sync?
• Replace os.walk's docstring with a reference of some sort to the RST docs (and probably do likewise for other functions)?
• Generally generate docstrings for modules from the RST docs programmatically as a build step, rather than having them in code at all?
• Remove os.walk's docstring entirely?
• Introduce validation of some sort that ensures the docstring and RST docs don't go out of sync?
• Adjust the two to match manually? (seems like a non-starter to me since it will likely go out of sync again)

Alternatively, both could be left as they currently are, but this seems like the worst of all worlds, neither doing anything about the sync issue nor improving either of the versions.

I'd be happy to send a PR to implement any of the less complex variations, but would appreciate some input from a maintainer regarding which is desirable.

[AA-Turner]

We intentionally have different docstrings and documentation, where docstrings are generally shorter.

What are the specific problems here with the os.walk docstring? It's more productive to address those rather than (foolish!) consistency. If the docstring is too long to be useful, we could consider pruning the text.

A

[AA-Turner]

cc @picnixz from the linked PR

[lheckemann]

I understand that docstrings and the RST docs serve different purposes and probably shouldn't have the same content. In this case, the texts are mostly identical, otherwise I wouldn't have raised an issue about it :)

[picnixz]

This doesn't answer this question:

What are the specific problems here with the os.walk docstring

If there are issues in os.walk docstring (that is something is incorrect but not imprecise), we must correct them. If it's just about consistency (that is the text differs a bit from the RST docs but highlights the same points, possibly ignoring other points), we won't change it.