Explaining source code via "doc"?

Question

Hi,

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?

Answer 1

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.

Answer 2

If you really feel the need to document something about the inner workings of a function, that mainly only the developers of the code need to know, phpDocumentor does have the @internal tag.

When you use the --parseprivate runtime option, non-public code elements (like private variables, protected methods, etc) become visible in your generated documenation. Text that you include via the @internal tag also becomes visible.

It sounds to me like the descriptions that you want to write regarding the internal method code would be good candidates for such @internal usage.