Type rewrite further improvement

[simonseyock]

Fixes openlayers/openlayers#10075

Because regex are inherently bad at matching nested structures and I had fun in digging into grammar and especially pegjs (https://pegjs.org/), I wrote a grammar to perform the type rewrites. I also made a branch (#12), but I don't know if this should be merged because it would introduce a new syntax that might be difficult to maintain if not known and a new dependency.

The parser approach has 2 big advantages: It can easily handle nested structures and it can throw errors if it finds expressions that it should be able to parse, but some type is missing.

Nevertheless I used this grammar to check the output of our regular expression and found several issues. I created a new regex that does not produce any false positives and only misses a handful of rewrites in the whole code base.

Examples for expressions it can not handle are multiline types and some strangely nested types.

  * @typedef {function(!SketchCoordType, SimpleGeometry=):
  *     SimpleGeometry} GeometryFunction

  * @param {{type: string,
  *     target: (EventTargetLike|undefined),
  *     propagationStopped: (boolean|undefined)}|
  *     BaseEvent|string} event Event object.

  * @type {!Object<string, (Array<Feature>|Feature|undefined)>} 

I also found some more incorrect annotations in the codebase, that I fix in PR on the main repository.

[simonseyock]

Also I found some types that where annotated like this: {module:ol/ImageState} which I don't know if they are correct. I would interpret these as the default export? I did not find something definitive in the jsdoc documentation.

[simonseyock]

One more thing is that @enum declarations are not detected as local types.

[simonseyock]

I added @enum rewriting and am now quite certain that this version works with all jsdoc comments except of 7.

Apart from the ones above these are:

 * @typedef {function(module:ol/Feature~FeatureLike, number):(Style|Array<Style>)} StyleFunction

 * @typedef {Style|Array<Style>|StyleFunction} StyleLike

 * @param {StyleFunction|Array<Style>|Style} obj

* @typedef {UniformLiteralValue|function(module:ol/PluggableMap~FrameState):UniformLiteralValue} UniformValue

[simonseyock]

@ahocevar can you look at this?

[ahocevar]

@simonseyock Thanks for your work on this. I think the nested ones you listed above fail because they are multi-line comments. Maybe putting them on a single line would make them work? And the last one you mentioned has an invalid type (module:ol/PluggableMap~FrameState).

So I think you did a great job with this. Thanks!