4 ms·
Python also uses autogeneration for most of the documentation, but the documentation itself is not fully autogenerated. You write your documentation and you say
by vbernat 10y ago
Python also uses autogeneration for most of the documentation, but the documentation itself is not fully autogenerated. You write your documentation and you say to Sphinx: put the generated documentation for this module here.
IMO, this is something positive. You can decide the structure of your documentation and include only the most relevant references.
For example, this part of the documentation for the re module is autogenerated from code: https://docs.python.org/2/library/re.html#module-contents https://docs.python.org/2/library/re.html#module-contents
- snovv_crash 10y agoAgreed, but my point is that argument and return types are badly documented, and in Python autogen doesn't help this.
- nitely 10y agoUsually there are examples for everything. Sometimes you have to scroll down, though. What the function returns is usually stated in the description. But I know what you are saying, actually most 3-party libs do document types. IMHO, python docs are ok. If you struggle with them as a beginner I don't see what would change as an advanced programmer.
- snovv_crash 10y agoI am an advanced programmer. I shouldn't have to read code snippets to figure out if a function returns a tuple or a 'group' which can be iterated over, but can't be indexed. This is something which would be fixed if the documentation included types, because then I could check what all the allowable operations on 'group' are directly without searching for a code snippet which does what I want or just running it and praying I got it right.