4 ms·

> he kind of technical documentation I love to read: precise Nothing precise about it. Method signatures don't even include a clear description of what they ca

• junke 10y ago
  The "text blob" always starts explaining precisely what kind of return value to expect under which circumstances. The return value's type can change depending on the context, and using plain text is somewhat easier to write and read than trying to come up with a dedicated notation. See findall[0], for example. The structure returned depends on whether the regexp has capturing groups or not. A specialized notation could be designed to represent that, but as far as I am concerned, the textual string is good enough. Just for fun, the return type could be expressed as: [string N] (A) | [(string M) N] : (M > 1) (B) - Case A if the regexp matches N times without overlapping and without capturing any group, or capturing a single group. - Case B if the regexp matches N times without overlapping and, for each match, captures a tuple of M groups, as strings. ... where [type size] denotes a list of size "size" satisfying the type description "type". Likewise, (type size) is a tuple of "size" elements, all of which satisfying the same type. Or you could write t1 * t2 like in other languages to define cross-products. [0] https://docs.python.org/2/library/re.html#re.findall https://docs.python.org/2/library/re.html#re.findall
  • nnq 10y ago
    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...)
    • junke 10y ago
      > 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 :) I agree, that was terrible. > My example of documenting re.findall all would be smth like this The hard part is to have everybody agree on the documentation mini-languge. https://www.python.org/dev/peps/pep-3107/ https://www.python.org/dev/peps/pep-3107/ https://www.python.org/dev/peps/pep-0484/ https://www.python.org/dev/peps/pep-0484/