Where to document functions in C or C++? [closed]

• Put the information that people using the functions need to know in the header.

• Put the information that maintainers of the functions need to know in the source code.

I like to follow the Google C++ Style Guide.

Which says:

Function Declarations

• Every function declaration shouldhave comments immediately precedingit that describe what the functiondoes and how to use it. Thesecomments should be descriptive("Opens the file") rather thanimperative ("Open the file"); thecomment describes the function, itdoes not tell the function what todo. In general, these comments do notdescribe how the function performsits task. Instead, that should beleft to comments in the functiondefinition.

Function Definitions

• Each function definition should havea comment describing what thefunction does and anything trickyabout how it does its job. Forexample, in the definition commentyou might describe any coding tricksyou use, give an overview of thesteps you go through, or explain whyyou chose to implement the functionin the way you did rather than usinga viable alternative. For instance,you might mention why it must acquirea lock for the first half of thefunction but why it is not needed forthe second half.

  Note you should not just repeat thecomments given with the functiondeclaration, in the .h file orwherever. It's okay to recapitulatebriefly what the function does, butthe focus of the comments should beon how it does it.

You should use a tool like doxygen, so the documentation is generated by specially crafted comments in your source code.