technical writing - How can I write better code-based reference documentation for programming interfaces?

Programmers can write comments in code that can be automatically turned into API documentation (like Javadoc). All I have to do is add some comments explaining what a class or method does and what arguments it takes, and software turns those comments and the signatures from the code into reference documentation. For example, I can write something like this in my code:

/* Finds the value for the given ID.
 * @param id  the item to look up
 * @return    the value

 */
 public String findValue(int id) {...}

Sounds great, but my readers tell me that my documentation isn't very helpful. I can't write a book in code comments but I want my documentation to be useful, so what should I be doing to make better API reference docs?

(I'm asking this on behalf of somebody else. Having already answered that person, I wanted to also answer it here.)