Improve MDN JSDoc wording - less wordy

[mihailik]

Search Terms

MDN JSDoc

Suggestion

A recent boost to dom.generated.d.ts #29690 brought in tons of MDN docs, which is super-helpful.

However, MDN format is well fit for Jane Austen, if not Mervyn Peake. For though sophisticated and corteous, 'tis not entirely fit for short form that is IDE tooltips and completions.

Perhaps, a fair bit of creative massaging can cut the introductions to a minimum?

The first thing to remove are introductions, repeating the name of the symbol, its type and various pocket lint words like 'this' 'represents' and so on.

---

I would suggest scrolling through the JSDocs added in PR DOM update February 2019 #29690 and making a set of 20-30 regex-assisted context-aware string replacers.

Then run DOM update scripts again with those, after which scroll through the JSDocs and nitpick if anything still needs tweaking. Hopefully not!

Next time DOM update is run, use those existing massaging string replacers, so the .d.ts stays lean and hungry.

Use Cases

IDE light-up features: tooltips, completions, signature tips.

Examples

/** The AudioTrack interface represents a single audio... more... wait... this text... is actually... what docs are for, not the intro at the start... why is it replaced... with ellipsis... ah I know, it's because that's how human perception works... it favours the start of the long paragraph... and of the HTML media elements, <audio> or <video>. .  */
interface AudioTrack {

Replace with:

/** A single audio track from one of the HTML media elements, <audio> or <video>.  */
interface AudioTrack {

Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

[mihailik]

@sandersn do you think it can/should be done?

I can either try to PR into your DOM processing scripts repo (where??) or implement a simple post-processing script here in this repo.

[sandersn]

Hooray! Somebody else who has heard of Mervyn Peake!

Anyway, this is in principle a fine idea. The file you want is https://github.com/Microsoft/TSJS-lib-generator/blob/master/src/mdnfetcher.ts. I see two obstacles:

1. Having the exact text from MDN makes things even more googleable. Probably not worth the extra verbosity, though.
   2a. String replacers are enough to get you started, but I suspect you'll want something more powerful, which means parsing or something.
   2b. Alternatively, using manual overrides like the rest of TSJS-lib-generator means that keeping the text up-to-date is a big task and less urgent than the types, so I'm worried that it might not happen.

I am definitely interested in a seeing a PR so I could compare the increased complexity with increased brevity. I don't think that string replacers would take much time to implement. You may get 80% of the benefit from just 2 or 3.

[mihailik]

Awesome, here is a quick PR for that:

microsoft/TypeScript-DOM-lib-generator#659

Updated baselines too -- easy to see the difference in wording. Must say I quite like the result!

[mihailik]

This now should be closed as updated typings are merged in TypeScript repository.

(unless it's waiting for the official release)