Basic JSDoc types - Plot.plot and all Marks

[duaneatat]

This PR uses a types.ts file for authoring the types (this is just for convenience, since I find it easier to write typescript types than use the JSDoc syntax), and we import those types as jsdoc tags where appropriate.

This PR covers Plot.plot and all of the marks.

Known issues:

• Some types are too broad, e.g. tickX doesn't accept x1 and y1, but those appear in the completions

TODO:

• Plot.image : move the description of options from the ### Image section to the Plot.image jsdocs

[duaneatat]

All of the changes to jsdoc-to-readme are about trimming the JSDoc so extra leading and trailing new lines don't end up in the README file. For some reason, when you have a JSDoc in a file that is just importing types, TypeScript returns empty lines for that JSDoc. This is benign but will result in a slightly cleaner README file.

[Fil]

I think I'd like to have all the types imports at the top of each file, as I was trying to do with the "import types" in #1005.

Maybe for later: I've tried to add a BarYOptions to the barY(data, options) mark, by creating

export interface BarYOptions extends MarkOptions {
  offset: null | "expand" | "center" | "wiggle" | function…;
  order?: "sum" | "value" | …;
}

Of course, it would have to be extended to cover all the stacking options, which means I'd want to write something like BarYOptions = MarkOptions & StackYOptions;. Not sure if this can be done with "type" or "interface", though.

[Fil]

[reminder for next steps:] I've just noticed that Plot.window(X/Y) and Plot.normalize(X/Y) have no jsdocs at all.

[Fil]

lgtm!

[duaneatat]

see #1055 (comment)

[mbostock]

Probably superseded by #1320 which goes the d.ts route. Close?

[Fil]

I'm good with closing, but let's keep the branch around for a while. There are a few things that I'll want to refer to, for example the to replace the D3 type:

/**
 * A symbol object with a draw function
 * @link https://github.com/d3/d3-shape/blob/main/README.md#custom-symbol-types
 */
type SymbolObject = {draw: (context: CanvasPath, size: number) => void};

[mbostock]

Superseded by #1343.