- What I would really like to see is that when someone spends the time to figure something out like this, they add an example/patch the comments in the files and then sends the patch off to someone to integrate :-)

I wouldn't like to see any of these situations. If functions were documented (by the writer), the user wouldn't have to figure out anything or write patches. I agree with Riccardo also, a lot of functions in IMP (mine included) are cryptic, or require some knowledge.

I agree it is better when the writer documents it, but there will always be cases where
- functionality is used in a way the writer did not foresee
- something that was clear to the writer was not clear to someone else
- corner cases that the writer wanted to leave ambiguous (to allow more flexibility with implementation, for example) are important to some user (here the act can act a a proposal to disambiguate the corner case)
And so I think (especially since the currently the writers don't always even document well enough for themselves), it is a good habit at least for people who otherwise contribute to IMP.