At the same time it must be possible to directly compile the code without need to a previous filter phase as needed when using e.g. cweb. Hence, the only place where to put documentation are comments. However, there are two types of comments, the programmer wants to distinguish.
Many programmers like to view the documentation online simply by klicking their mouse buttons.
A standard for such documents is HTML for which good viewers are available on almost every machine. Doesn't it look ugly, compared to what one is used to. For both ouput formats, it is important that the documentation is well structured. The best way to read such a hierarchy is by looking at a picture of it.