Module annotations wouldn't half help

As a beginner at PHP with some understanding of Drupal, I have been struggling with module enhancements that I can't do without. What I want to do is relatively simple. Some is done and works, but what is more difficult is understanding some esoteric module code that is over my head. Trying to figure out exactly what it does and how the logic flows is like trying to read the Rosetta stone. Even a couple of lines comment about each custom function would help enormously (as the Drupal API docs do regarding Drupal functions).

Iit occurs to me that it would be helpful for each project page to list a thoroughly annotated version of each released module. Nobody is going to want tons of text bloat in distributions. Although I'm sure many of the gods working at development are able to read un-annotated code just fine because they are expert programmers, it would surely help many aspiring well-meaning twerps like me get up to speed faster. Ah, so that's what it does (and why)...

Developers who have worked on a module must have all this stuff in their heads by the time it is released. It seems slightly ungrateful to ask them to ask them to please do a bit more work and write it down rather than discard it (and I bet a lot of modules are stuffed with comments during development that actually get stripped out before release), but it'd probably reduce forum puzzles & support requests and make up for a general lack of documentation.

Or am I asking for something that's silly, because anybody who can't understand hard code should not be tinkering?