Search code examples
documentationcommentsphpdocjsdoc

Explaining source code via "doc"?

I am using PHPDoc and JSDoc for my source code. I know that there are tools to build an API out of those docs. However, what I am wondering is that how is one supposed to explain complex code? Do I just use multiline comments inside functions rather than explaining in the PHPDoc/JSDoc?

For example, consider this code:

/**
 * Lorem ipsum dolor sit amet.
 * @param {Integer} width
 * @return {Boolean}
 */
function setWidth(width) {
 // Very complex code goes here...
}

In the above case, how should I go for commenting the complex code? I do not think I can do that in the JSDoc since it is used for building an API (which is about "how to use" rather than "how things work"), right?

Are my assumptions correct:

  • JSDoc/PHPDoc is solely written for those who are going to use the function/method.
  • Comments within the function are written for anyone who needs to understand the logic behind the function/method.
  • Documentation is separate from API and source code comments, the documentation (that every software should provide) is written for those who want to use the software.

But what I do not understand is that what explains the software in an architectural level -- should there be a developer documentation, too?

What are your strategies to perfect documentation?

Solution

  • You document Public Interfaces with those tools, you don't want consumers of the API to know or care about the implementation details, you put those comments in the code itself. Also "perfect" documentation is not really a good goal. The BEST documentation is working example code that uses the Interfaces in a obvious manner. Unit tests fit this requirement nicely in most cases.