in reply to On comments
There's been a lot of comparing software development to building erection, machine shops, and other physical construction types of tasks lately. Let me draw some parallels, then, to certain products for those tasks. A furnace, water heater, circular saw, drill press, or welder has more than one type of documentation. Those are located in different places for different audiences and for different purposes. There's the user's manual. That tells people how to use the device day-to-day and where to get optional attachments and expendable replacement parts. Then there's the maintenance manual that covers how to fix broken devices and where to get replacements for the permanent parts of the device the end user shouldn't be bothered to replace. Then there are warning stickers near places where electricity, hot surfaces, moving parts, lasers, or sharp edges cause particular dangers. These are for anyone: the end-user, the maintenance worker or repair shop, or a curious visitor. They draw attention to certain areas to avoid and warn people to be careful around certain parts no matter what their level of intimacy with the device.
A big part of the issue here is that the user and the maintenance programmer can often find the same type of documentation about the program, even though it is for different audiences. That type is prose about how to use features of the program to do things which is found separately from the code. The only difference between this type for the end user and for the programmer is which features are covered. Think of these as the user manual and the maintenance manual for your plumbing and heating fixtures or power tools. For the end user, features of the user interface and how to operate the program are covered. For the maintenance programmer, features of the programmer interface (APIs, data formats, extension mechanisms, callback hooks, and more) and how the parts work together are the topics. Those are definitely features, and they can form what is clearly an interface. Many programmers, especially for a large and complex program, want this sort of documentation ever as much as the end user does. They want the developer interfaces covered with as much care and detail as the end-user interface.
Comments can be documentation, too. They should not be the sort of documentation mentioned above, though. A comment placed locally in a particular section of code should be used only to convey information germane to that local section of code. If there's for example a line that seems superfluous but works around a serious security risk and therefore shouldn't be removed for the sake of speed or efficiency*, it is my opinion there should be a comment about that line right there. If there's some reason a section of code looks crufty because it's working around a bug in a lower layer of software, you probably want to document that right in the code with a comment, too. Think of these comments as "attention" or "warning" labels near the hot, sharp, blinding, or crushing parts of the device.
The comments really shouldn't be the place you document everything a programmer needs to know about APIs and data formats. The POD or external documentation in some other format really shouldn't be the only place an important security, speed, or bugfix hack in the code is mentioned. You might want to mention it there as well, but comments immediately above or to the side of the code the next programmer might try to edit is the safest place to put such "warning label" documentation.
* This actually happened in part of the Linux kernel somewhat recently. A line of assembly code for the AMD and Intel x86_64 processors (which zero-filled a register) was removed which lead to a local root exploit. To someone without proper knowledge, it looked like a wasted CPU operation. The same bug had been fixed in 2007 (CVE-2007-4573) in Linux 2.6.22.7 and was reintroduced at some point. It was rediscovered as a vulnerability in 2010 (CVE-2010-3301). Had there been a clear enough comment close enough to that line in the code, perhaps the vulnerability would have stayed closed.