At work, we mostly use C and some C++. We use Doxygen to document it. All of the public stuff of a module is located in its header file, and so is the doxygen markdown for the public stuff. The private stuff and the implementation of public functions is in the C file, and we document it very much like the header file. That way, we can (hopefully) understand our code even in five years from now. Doxygen has the flags EXTRACT_ALL, EXTRACT_PRIVATE, and EXTRACT_STATIC that we set to YES to get the complete documentation. In some cases, the documentation of the public stuff is sufficient, so we can set those flags back to NO and get a much smaller documentation.

For helper code (perl, bash, Windows batch files), we do roughly the same, often by using doxygen with a custom input filter.

Code documentation is usally only a small part of our work. Medical and aerospace products require tons of paperwork, and the overhead grows with every new issue of the relevant standards. So documenting all of our code does not only help us maintain the code base, but also fulfils some obligatory requirements from the standards. And those of our clients that have bought the source code also get the complete documentation so they can modify the source on their own. Few clients actually do that, but they like the idea that they could.

In my perl code, I usually document everything, simply because I rarely need to touch my code. Documentation clearly helps to understand what I did years ago.

Alexander