You may not remember, but you and I have had this discussion while working together. You were probably one of the people mocking me. ;-)

> I never actually trust that documentation to be accurate or up-to-date. I expect it to be misleading and time-wasting, and so I only trust the code itself.

Two things here:

1) I don't implicitly trust comments. Obviously, the code is the definitive source of reference, and where the comment differs from the code, it only means that something interesting happened. But...

2) I believe in commenting "why" or "who", and less often, "what" (and rarely "how"). My experience is that "why" comments age well -- even if the code drifts, the intent of a method or class changes infrequently.

For example:

  # I (timr) wrote this method because I needed a way to 
  # invert the index for {situation}, and {method a} and
  # {method b} didn't work because {reason}.

is a better, more evergreen comment than:

  # this method inverts the index for {situation}.

which is far better than:

  ## 
  # inverts index.
  # @args foo, bar, baz
  #

Unfortunately, nearly all doc generation software encourages the latter, and so many comments are pretty darned useless. The first example is great because even if {method a} and {method b} and {reason} fail to be true in the future, some other programmer can come along and read it and say "ok, I understand why this was written this way, and the preconditions motivating it are no longer valid. maybe I can refactor."

This is hugely valuable.