Improve documentation for dom methods

[mjbvz]

From microsoft/vscode#65256 (comment)

TypeScript Version: 3.3.0-dev.20181214

Search Terms:

Code
For the JS

document.createElement('button').addEventListener

Hover over addEventListener

Bug:

The returned documentation is not very end-user friendly or well formatted. Here's the text we get back:

    "documentation": "Appends an event listener for events whose type attribute value is type. The callback argument sets the callback that will be invoked when the event is dispatched.\nThe options argument sets listener-specific options. For compatibility this can be a\nboolean, in which case the method behaves exactly as if the value was specified as options's capture.\nWhen set to true, options's capture prevents callback from being invoked when the event's eventPhase attribute value is BUBBLING_PHASE. When false (or not present), callback will not be invoked when event's eventPhase attribute value is CAPTURING_PHASE. Either way, callback will be invoked if event's eventPhase attribute value is AT_TARGET.\nWhen set to true, options's passive indicates that the callback will not cancel the event by invoking preventDefault(). This is used to enable performance optimizations described in §2.8 Observing event listeners.\nWhen set to true, options's once indicates that the callback will only be invoked once after which the event listener will\nbe removed.\nThe event listener is appended to target's event listener list and is not appended if it has the same type, callback, and capture.\nAppends an event listener for events whose type attribute value is type. The callback argument sets the callback that will be invoked when the event is dispatched.\nThe options argument sets listener-specific options. For compatibility this can be a\nboolean, in which case the method behaves exactly as if the value was specified as options's capture.\nWhen set to true, options's capture prevents callback from being invoked when the event's eventPhase attribute value is BUBBLING_PHASE. When false (or not present), callback will not be invoked when event's eventPhase attribute value is CAPTURING_PHASE. Either way, callback will be invoked if event's eventPhase attribute value is AT_TARGET.\nWhen set to true, options's passive indicates that the callback will not cancel the event by invoking preventDefault(). This is used to enable performance optimizations described in §2.8 Observing event listeners.\nWhen set to true, options's once indicates that the callback will only be invoked once after which the event listener will\nbe removed.\nThe event listener is appended to target's event listener list and is not appended if it has the same type, callback, and capture.\nAppends an event listener for events whose type attribute value is type. The callback argument sets the callback that will be invoked when the event is dispatched.\nThe options argument sets listener-specific options. For compatibility this can be a\nboolean, in which case the method behaves exactly as if the value was specified as options's capture.\nWhen set to true, options's capture prevents callback from being invoked when the event's eventPhase attribute value is BUBBLING_PHASE. When false (or not present), callback will not be invoked when event's eventPhase attribute value is CAPTURING_PHASE. Either way, callback will be invoked if event's eventPhase attribute value is AT_TARGET.\nWhen set to true, options's passive indicates that the callback will not cancel the event by invoking preventDefault(). This is used to enable performance optimizations described in §2.8 Observing event listeners.\nWhen set to true, options's once indicates that the callback will only be invoked once after which the event listener will\nbe removed.\nThe event listener is appended to target's event listener list and is not appended if it has the same type, callback, and capture.\nAppends an event listener for events whose type attribute value is type. The callback argument sets the callback that will be invoked when the event is dispatched.\nThe options argument sets listener-specific options. For compatibility this can be a\nboolean, in which case the method behaves exactly as if the value was specified as options's capture.\nWhen set to true, options's capture prevents callback from being invoked when the event's eventPhase attribute value is BUBBLING_PHASE. When false (or not present), callback will not be invoked when event's eventPhase attribute value is CAPTURING_PHASE. Either way, callback will be invoked if event's eventPhase attribute value is AT_TARGET.\nWhen set to true, options's passive indicates that the callback will not cancel the event by invoking preventDefault(). This is used to enable performance optimizations described in §2.8 Observing event listeners.\nWhen set to true, options's once indicates that the callback will only be invoked once after which the event listener will\nbe removed.\nThe event listener is appended to target's event listener list and is not appended if it has the same type, callback, and capture.",

The current formatting is rendered as a single big block. I'm not sure what the purpose of the newlines is but they do not seem to mark paragraphs

Playground Link:

Related Issues:

[weswigham]

AFAIK the text (including newlines) is pulled straight from the whatwg IDL. You're correct in that the newlines are a bit strange:

[mjbvz]

The mdn documentation may be more helpful to most developers: https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener

Looks like #26404 may be looking into this

[weswigham]

@sandersn you've been looking over the TSJS repo right now, right? Wanna look at the stuff associated with #26404 ?