Your thinking is correct and precise, but I hope you never take a job of documentation writer for any project I will ever have to work with :) My example of do

Your thinking is correct and precise, but I hope you never take a job of documentation writer for any project I will ever have to work with :) My example of documenting re.findall all would be smth like this: Signature: re.findall(pattern, string, flags=0) -> [str] or [(str,)] Arguments: ... Returns: - [str] -- List of Strings matching the pattern if the pattern has no capturing groups, or only one capturing group - [(str,)] -- List of Tuples of Strings, one string for each captured group, if the pattern has more than one capturing group Examples: re.findall(r"h(\w{0,10}o)", "hello hoolo water") # -> ['ello', 'oolo'] re.findall(r"h(\w{0,10}o)", "hello hoolo water") # -> ['ello', 'oolo'] re.findall(r"(h)(\w{0,10}o)", "hello hoolo water") # -> [('h', 'ello'), ('h', 'oolo')] Details: ...put here some deatailed explanations about behavior with overlapping etc.... This is the kind of documentation that really spares me a lot of time. Your explanation may be correct but I'd have to read it 5 times and then open a REPL to do a small experiment and confirm that it means what I thought it means... (I now I don't have the right to bitch about this though, the correct thing to do would be to donate some of my time and actually improve the existing docs instead of commenting on hn...)