Hacker News Reader

Worse than that, it can get out of step with the method signature. A lot of tools I've seen will take the doc comment as an authority over the method signature, even if they don't match up.

Javadoc-style for documenting method behaviour is quite often very useful for explaining the edge cases and stuff like that. I wish I could just document the parameters that are interesting, and have the tools merge that with the method signature.

View on HN

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.

Reply on news.ycombinator.com