File-level docblocks are being treated as method level blocks

[tdmalone]

Input code:

/**
 * @file This is my module.
 * @author Tim Malone
 */

'use strict';

Linter output:

/index.js
  1:1  warning  could not determine @name for hierarchy

Output documentation:

## 

This is my module.

**Meta**

-   **author**: Tim Malone

What I expected to happen:

I'm trying to use the @file tag to explain the purpose of the file. It looks like Documentation is parsing this as a 'virtual comment', and is looking for @name.

(At first I thought it was expecting the name of the package, which I was expecting would be automatically inferred from the package.json).

It's possible I'm misunderstanding the purpose of the @file tag. I was hoping to get a description of the file within the documentation - or at the very least, not have the linter ask for the name of it ;).

• What version of documentation.js are you using?: v5.3.5
• How are you running documentation.js (on the CLI, Node.js API, Grunt, other?): CLI

[tmcw]

Sorry, the @file tag isn't supported in any of the output modes at this point. It's a JSDoc feature that is implemented in the official JSDoc parser, but not yet here. Happy to review & merge a PR implementing support.

In dx-spec, we're likely dropping the @file tag because it's unclear whether source files should have any representation in documentation. Given that the recommended method of consuming JavaScript modules is from the module entry point, documenting in the public API where the methods come from has uncertain value.

[tmcw]

Closing - happy to review any PR that adds @file support, tracking tags in #9