documentationjs / documentationjs/documentation

Declare a class in a namespace using dot

Open
#1,301 0 comments 1 reaction 0 assignees View on GitHub
Dominant language
JavaScript
Stars
5.8k
Forks
481
PR merge metrics
No merged PRs in 30d

Description

**If you're reporting a bug, please include _input code_, _output documentation_,
a description of what you expected to happen, and what happened instead.**

* What version of documentation.js are you using?: 12.1.3
* How are you running documentation.js (on the CLI, Node.js API, Grunt, other?): no

I'm using the following JSDoc annotated JavaScript file:
**Input**
```js
/**
* @namespace
*/
const Extensions = {}

/**
* @class Extensions.Registry
*/
const Registry = Extensions.Registry = {}

/**
* @memberof Extensions.Registry
* @inner
* @function getGroups
*/
Registry.prototype.getGroups = () => {}
```

As you can see, I want to declare a namespace named `Extensions` and a class named `Registry` inside this namespace (using the dot notation).

Here's the result with `jsdoc`:

**Output** (using [jsdoc](https://www.npmjs.com/package/jsdoc))
![jsdoc](https://user-images.githubusercontent.com/333276/71547640-cd0f6380-29a2-11ea-9793-5777a4d4c7ca.png)

As you can see the class `Registry` is in the namespace `Extensions` (as expected)

For reference, here's the result using `tsd-jsdoc`:

**TypeScript Definition** (using [tsd-jsdoc](https://www.npmjs.com/package/tsd-jsdoc))
```typescript
/**
* @namespace
*/
declare namespace Extensions {
/**
* @class Extensions.Registry
*/
class Registry {
/**
* @memberof Extensions.Registry
* @inner
* @function getGroups
*/
getGroups(): void;
}
}
```

And now, here's the result using `documentation`:

**Ouput** (using `documentation build file.js -f html`)
![documentation](https://user-images.githubusercontent.com/333276/71547639-ca147300-29a2-11ea-8517-c07b407142e9.png)

As you can see the class `Registry` is *not* in the namespace `Extensions` and the `getGroups` function is not attached to the `Registry` class.

**Ouput** (using `documentation lint file.js`)

```console
$ documentation lint file.js
/path/to/file.js
12:1 warning @memberof reference to Extensions.Registry not found

⚠ 1 warning
```

If I replace `Extensions.Registry` by `Extensions/Registry` then it's working in `documentation` but not `jsdoc`:

**Ouput** (using `documentation build file.js -f html` with `/` as a separator)
![doc-good-slash](https://user-images.githubusercontent.com/333276/71547673-2d9ea080-29a3-11ea-9ff5-fee23ae1306c.png)

**Ouput** (using [jsdoc](https://www.npmjs.com/package/jsdoc) with `/` as a separator)
![jsdoc-bad](https://user-images.githubusercontent.com/333276/71547691-76eef000-29a3-11ea-9674-d48535b4b4b3.png)

As you can see the class is named `Extensions/Registry` and is not part of the namespace `Extensions`.

I think we should use dot as a separator instead of slash to be consistent with JSDoc (or at least support both syntax).

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.