Not only are you right that these docblock comments can get out of sync with the real parameters, but I would argue that it is almost inevitable that they will.

Not only are you right that these docblock comments can get out of sync with the real parameters, but I would argue that it is almost inevitable that they will. I rarely waste my time reading them any more, but when I do, there's something out-of-date more often than not. I like your idea of documenting only the interesting aspects of the parameter list. I'd advocate just going ahead with it, using plain old concise English prose to do so. Comments are supposed to be for humans to read anyway.