I was recently creating a small technical documentation for an application. The document is to be used by newly hired programmers to get acquainted with the application. It is much friendlier than the Javadocs we have, and includes information that usually isn't being documented.
When describing a function, I first bring the prototype and than the description, usage, etc. I have to choose to include argument names or omit them in the prototypes. On one hand, argument names are mostly trivial (like
MyClass myClass), on the other hand they sometimes contain information of the purpose of the argument (which I will indicate when describing the function anyway).
I had the same dilemma in C++ when creating a class in two files.
Should I include argument names? Does it really work for readability?