Regarding docstrings..yes that would be a great help.
Regarding comments..about a year ago I suggested that newbies 
especially would appreciate better commented code for the 
examples in the manual for one, but especially in csd's that are 
submitted as examples and in those submitted as works for others 
to study.  I've found many interesting pieces in the csound 
catalog, for example, that are straight uncommented code, 
offering no clue about how or why choices were made for 
particular opcode choices, or for why they were combined in the 
way they were.  I probably learned a lot by trying to puzzle 
them out..but then I kinda like codes and ciphers anyway.  Even 
so, I kept (and keep) wishing for better comments.  To tell the 
truth, every language I've ever studied, and every programming 
class or tutorial I've ever dealt with stresses the need for 
commenting code.  Thanks for suggesting that the practice can be 
as helpful for the programmer as much as it is for the user.
Bob Foose