I quite liked these guidelines for documenting code:

1. explain the motivation 2. give at least one example of usage 3. explain implementation choices

(Not saying this is the best way - there are lots of different guidelines for documenting code that I like!)