I think the big difference is what type of information you're looking for. The code is the final arbiter on what the program does, but gives incredibly little

I think the big difference is what type of information you're looking for. The code is the final arbiter on what the program does, but gives incredibly little information about why it is designed that way. * Can be learned from the code: Function A accepts a C-style pointer to a data array. * Can be inferred from the code: Function A is called in an inner loop, and so it probably accepts that data array to avoid doing any memory allocation. * Cannot be known from the code: Even though the data array is initialized to 0 in the current code, function A should not assume that will always be the case. That data array is intended to be used as persistent storage in a future version. The first one is kind of pointless to document beyond what doxygen already gives you. The second is useful, but not necessary. The third is absolutely essential, because nothing in the current code can possibly tell you about the future intents for changes in the code.