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.)
No comments:
Post a Comment