What purpose does a list of one line routine summaries serve?

... same end in a quicker/easier fashion.

sub flip_pancake
[download]

Also more robust. As you say, this only goes so far, but your technique doesn't go much further.

The problem with your technique is that it doesn't scale well. Once a routine requires more text than you want on a line, you are tempted to abbreviate your comment unreasonably. Once you have more developers involved the technique is destroyed by formatters and pretty printers.

Comments and documentation are time and/or space travelers. When I write comments as you've described; and I have over years. I write them now and bury them in a time capsule; when I dig them up three years hence, I find I am a different person. A person who finds them useless for being redundant or for being obscure. It is for that future person that I should write.

The comments I am apt to put on that line are too close to the code. Not too close textually or lexically, but too close in meaning--they say the same thing almost the same way. They shed the same light as the code; by being so similar, they can be understood or misconstrued in the same manner as the code.

The more experience I have with comments that have aged, the less value I usually find in the brief ones.

Having a better tool than a simple grep helps; consider the B or C options to grep or things like ctags.

Be well,
rir