Skip to content

Conversation

@tschaub
Copy link
Member

@tschaub tschaub commented May 16, 2019

When there is a description below an @abstract tag, JSDoc emits warnings like this:

WARNING: The @abstract tag does not permit a value; the value will be ignored. File: Layer.js, line: 118
WARNING: The @abstract tag does not permit a value; the value will be ignored. File: Layer.js, line: 122

(The things that are frustrating about this are the lack of path, the wrong line numbers, and the repetition. Perhaps the repetition and wrong line numbers are due to us manipulating the file in a plugin.)

In the case above, the @abstract tag is not parsed (not available to a plugin that might want to do something with it) and the description is lost. When the description is placed above the @abstract annotation, things are properly parsed.

Similar situation with @module. But no warning here. When there is a description below a @module tag, the doclet's longname includes the description.

When the description is below, the doclet includes this:

"longname": "ol/worker/version\nA worker that responds to messages by posting a message with the version"

When the description is above, the longname is properly set to "module:ol/worker/version".

Copy link
Member

@ahocevar ahocevar left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks!

@tschaub tschaub merged commit 6d06f81 into openlayers:master May 16, 2019
@tschaub tschaub deleted the fragile-docs branch May 16, 2019 22:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants