[randomdata]

> Remember that comments and documentation are no substitute for proper testing that will expose usage errors.

Which is pretty much what I was getting at. Consider the following pseudo-code:

  Verify account takes an account ID, an optional enabled flag which, if
  specified, will only search for accounts that have a matching enabled
  status. The default is to search against all accounts. The return
  value is true if the account is valid, false otherwise.:

    account = new Account(id: 1)
    assert account.search does_not_include id != 1

It is human readable and machine parseable. You get your documentation, usage examples, and tests all in a place that is far better suited for the job, in my present opinion. I welcome being swayed though.

(I'm not sure that code even matches what your comment describes, but I couldn't really figure out what the comment was supposed to really intend the code to do, which brings me all the way back to my original points. Sorry.)