For 99% of JS classes, there is no constructor description and instead
the class/constructor are defined together followed by both `@class`
and `@constructor` in the same block. These are interpreted as the
description belonging to the class and prominently displayed in the
documentation.
For the very rare cases where a constructor has its own description,
this must follow the tag rather than preceed it. This makes sense
when thinking about it in terms of how classes are usually defined
(above the constructor, and thus the space above `@constructor`
already belongs to `@class`).
This has the unfortunate side-effect, however, that when a constructor
is documented on its own, that any text above `@constructor` is
ignored, as happened with mw.Api.
But, as so often with strict documentation warnings, it helped uncover
a mistake. The text here is quite useful and not really specific to
the constructor and more broadly useful for the module as a whole,
as such I moved it to the class block.
Also:
* Clean up the code by bringing the class and constructor definition
back together.
* Fix warning about invalid internal reference:
> Warning: /resources/src/mediawiki.api/index.js:3: {@link https://…}
The `@see` tag is only valid when referring to another index entity.
There were three other uses of `@see` with a URL in core, but only in
`@ignore`-ed code, which this commit fixes at the same time.
Follows-up a28b76abe9.
* Use local `var` declarion for `promises`, since "one-var" style
is no longer current.
Change-Id: I2d4f8b99c2896d4e1af50956c9faa8b36344884e
1917ed656c