What information should go into file-level document block?

Question

I primarily develop for Node.js. I got into a habit of putting a file-level docblock into all of my .js files. It looks something like this:

/**
 * project-name
 *
 * Licensed under the BSD-3-Clause license
 * For full copyright and license information, please see the LICENSE file
 *
 * @author     Name <email>
 * @copyright  Year Name
 * @link       project-repository-url
 * @license    http://choosealicense.com/licenses/bsd-3-clause  BSD-3-Clause License
 */

// Code starts here...

When I started with Node.js, this seemed like a good idea to describe what project the file belonged to, how it was licensed and who was the author. Before Node.js I worked a lot with PHP and some documentation tools even recommended/required such file-level docblock.

Recently, though, I started feeling like a lot of that information is redundant:

• Licensing information is available in the LICENSE file
• Authorship/copyright information is available in the package.json / composer.json / whatever file
• The fact that license information is in LICENSE file is nowadays a well-known fact

And so I am left with maybe the project's name. Since I do not like the feeling of completely removing the file-level docblock (it feels as if something is missing), I ask thee:

What information (if any) should go into file-level docblock?

To make the question a bit more factual than opinion-based:

• What was the original motivation/intent that people started writing these file-level docblocks?

  I suspect this will be something along the lines "In the early 90s..."

• How does that intent translate into current modern software development environment? Are any of those intents still valid/reasonable?
• Is there any other information I might consider adding to a file-level docblock that I do not already have there?

Answer 1

Repeating information at the beginning of each source code file makes IMHO only sense to minimize the risk of separation of license & copyright information from the particular file. So if that information is already stored elsewhere, the absolute minimum you should add is a reference to the place where to find that information. If someone sends you a single source code file as an email attachment, the project's name is probably not enough to find out what license the code is under or where to find the license information. So having a hint in the source code file that there is an additional license file gives you the chance to ask the person who send you the mail to add the missing files.

If many people have access to the source code, like in open source projects, the more important it becomes to prevent the separation. And when you have different contributors to a project, there might be different copyrights, different authors, and individual license conditions for individual source code files. For such projects, it seems to be reasonable to provide a bigger, standardized docblock, with placeholders for all the information you listed above.