Post History

Source: https://writers.stackexchange.com/q/10501
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

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.)

Original score: 8