What is formal documentation?

Question

On the website of W3schools they mention the expression "formal documentation".

It is Most common to use single line comments.

Block comments are often used for formal Documentation.

What is a formal documentation?

Answer 1

This means that the comment will be used to create documentation.

The formal documentation comment should be public and is often used to create external documentation in a more presentable way for a human.

There will be the name of the object, the function, the expected parameters, the return, what they do, what care to take, eventually an example of use and other related subjects. So these comments give a basis for the programmer who is consuming that know how to use.

This documentation shows the contracts that the consumer of this object/function will have to fulfill to use correctly.

The statement of the site cited (which is known to be a bad reference and responsible for many people learning wrong) gives room for interpretation. It is not wrong because it uses words that accept another interpretation but induces people to think that it occurs so much, curiously the examples used show the opposite. W3schools mixes concepts and does not actually speak what is formal documentation, nor does it show. Having many lines has nothing to do with ordinary comment or documentation, although documentation will always have many lines. This is an example of formal documentation:

/**
 * Summary. (use period)
 *
 * Description. (use period)
 *
 * @since      x.x.x
 * @deprecated x.x.x Use new_function_name() instead.
 * @access     private
 *
 * @class
 * @augments parent
 * @mixes    mixin
 *
 * @alias    realName
 * @memberof namespace
 *
 * @see  Function/class relied on
 * @link URL
 * @global
 *
 * @fires   eventName
 * @fires   className#eventName
 * @listens event:eventName
 * @listens className~event:eventName
 *
 * @param {type}   var           Description.
 * @param {type}   [var]         Description of optional variable.
 * @param {type}   [var=default] Description of optional variable with default variable.
 * @param {Object} objectVar     Description.
 * @param {type}   objectVar.key Description of a key in the objectVar parameter.
 *
 * @yield {type} Yielded value description.
 *
 * @return {type} Return value description.
 */

I put in the Github for future reference.

You can use a tool like Jsdoc to read this and create the documentation for you.

You might wonder if this is really that formal but they probably meant it’s not a private, temporary comment, just to inform the implementers of that.

Common comment

He’s in opposition to common comment which says something specific to the code and internal that indicates some problem or because an internal decision has been made. The common comment talks about the code, it explains decisions made, it is for the authors of the code and people who will read the internal code. Even common comments should not give details of what you are doing, the code should be readable so you do not need it. Common comments must be rare and explain why you did what you did and not what you did.

Some common comments occupy more than one line because they explain why. But this doesn’t make them formal documents, one thing has nothing to do with the other.

Learn more about common comments. And explaining why comments should not be used. Documentation comments are always welcome unlike common ones.