I once asked Paolo Veñegas, "why does Sacha say Emacs is so cool?" Yesterday, he showed me several features of Emacs which are coming close to convincing me of its coolness. He quoted from GNU, "Emacs is the extensible, customizable, self-documenting real-time display editor." I, of course, asked "how can it be self-documenting?" I didn't quite get the explanation. Something about comments being directly in the ELisp code as opposed to being external. That isn't really "self-documenting," I replied. "You still have to type the comments in. That's you doing the documentation and not the computer." It was then that I got this cool idea.
What if there really was a way for code to document itself? I wonder if, with more knowledge of compiler theory, I could write some sort of program that actually parses code, and automatically adds English documentation based on the contents? It would naturally, be no replacement for actual documentation, but it nevertheless could be great for people who have to work with undocumented code (or are to lazy to make documented code).
It seems stupid at first. The documentation would read like "This method increments the 'foo' variable by one. It creates a socket. It calls..." and so forth.
I think, however, that there this could have much more potential. Can we make the program learn to recognize patterns? "This program sorts an array." "This program creates a socket whose port number is the sum of two numbers." Sure, it would be a weak program at first, but imagine if it works well! A new generation of lazy programmers would be born!