Totally and completely wrong!
The code is How.
Doc comments are What
Annotation is Why.
You've got the entire thing bass ackwards
The requirement is to show Customer A's Invoices
For that you need something that will return a list of invoices for customer.
You need a set of unit tests that will prove that you can get 0,1 or many of something called invoice for something called customer that doesn't miss any.
After that how is irrelevant is to what ever is calling the code. If it is then your code is crap, and no amounbt of dicumentation is ever going to make it better.
Documenting after will always fail in a commercial environment, because once the code is deemed good enough, the resources required to go through and document it will disppear before you've run up the tool to do it.
Developers let their comments get out synch, sheesh.
Keep Up with TechRepublic