documentationjs / documentationjs/documentation

@file is applied to following element instead of the file itself

Open
#1,178 1 comment 4 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
5.8k
Forks
481
PR merge metrics
No merged PRs in 30d

Description

If you use the `@file` statement to provide a description for your file in a header, it gets applied as a duplicate block to whichever element comes first in the file.

Example code:
```
/**
* @file Example file.
*/

/**
* Example class.
*/
class Example {
/**
* Example function.
*/
a() {
}
};
```
Here, the `@file` block should effectively be ignored, however `documentation` currently applies it to the following item, so in this case the `Example` class is duplicated.

I think if a docblock contains `@file` it should be ignored, or at least attached to the file and not to whatever element follows the block.

Here is the output of the above code, with the duplicate `Example` class:
```
### Table of Contents

- [Example][1]
- [a][2]
- [Example][3]
- [a][4]

## Example

Example file.

### a

Example function.

## Example

Example class.

### a

Example function.

[1]: #example

[2]: #a

[3]: #example-1

[4]: #a-1
```
Running 8.1.2 via CLI.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.