Your reference example includes lots of details, examples of usage including source, explanation of options, etc. :)

That's not an "easier to keep documentation up to date" type of thing ;), but is definitely an example of good documentation.

Unlike the Apple approach mentioned above. :( :( :(