What is the correct term for the documentation that we put just above a method declaration?

Question

I'm writing a whitepaper and realized that I am not sure what the official term is for the kind of internal documentation that we put as a comment block before a declaration of definition.

The same thing that eventually becomes JavaDoc member documentation.

It's not simply internal documentation, and I'm not sure "header documentation" would be a good term.

Note that I'm looking for a general term, not one specific to a particular language (e.g., Java/Perl)

Answer 1

This is called a method specification or procedure specification. That is, it specifies the behaviour of the procedure rather than the implementation details. Some text books refer to it as the contract of the method but that may be a bit ambiguous.

Answer 2

At my organization we call it a method or function doc-comment. Function-level documentation is probably the more widely used term.

Answer 3

I always call it method (or function) comment, to distinguish it from class or file comments.

Answer 4

It's often professionally referred to as a "requirements clause", or an "insurance clause".

Answer 5

I usually refer to it as "inline documentation." To me that's what it's about — the fact that your documentation is in your source code, so there's more of a chance the docs will stay in sync with the code.

(This is no guarantee, of course, but it does encourage programmers to eat their vegetables. It means the developer can change the documentation at the same time and in the same place the behavior changes, rather than after the fact and in another place.)

Answer 6

I call it code comments, simple like that.