For the first question, putting the documentation into the source code has a major problem, there is no good place to put an overview of the whole system. Block diagrams are difficult to draw with just ASCII, images can't be included, formulas, and more. Also many things in software connect to many other things, and if the documentation is in the source code you can likely only describe one side of these connections (or you have to describe both fully on each side of the connection, thus duplicating a lot of the documentation.) Comments are immensely useful, but I don't think they work for general purpose documentation of a system. They can work well for libraries where each API needs to be described separately, but even then I wouldn't consider them complete documentation of a library (how do you combine graphics functions to build a rendering pipeline for example, do you have to described how to build pipelines for every single function that might be used in a pipeline?)