Skip to content

Commit 090ad3a

Browse files
FilFil
authored
normalize links in JSDoc comments: (#1794)
- use link number format - move github/d3 to d3js.org - add https
1 parent 7e458ff commit 090ad3a

File tree

6 files changed

+64
-54
lines changed

6 files changed

+64
-54
lines changed

‎src/format.d.ts

Lines changed: 12 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,12 @@
22
* Returns a function that formats a given month number (from 0 = January to 11
33
* = December) according to the specified *locale* and *format*.
44
*
5-
* @param locale a [BCP 47 language tag](https://tools.ietf.org/html/bcp47);
6-
* defaults to U.S. English.
7-
* @param format a [month
8-
* format](https://tc39.es/ecma402/#datetimeformat-objects): either *2-digit*,
9-
* *numeric*, *narrow*, *short*, *long*; defaults to *short*.
5+
* @param locale a [BCP 47 language tag][1]; defaults to U.S. English.
6+
* @param format a [month format][2]: either *2-digit*, *numeric*, *narrow*,
7+
* *short*, *long*; defaults to *short*.
8+
*
9+
* [1]: https://tools.ietf.org/html/bcp47
10+
* [2]: https://tc39.es/ecma402/#datetimeformat-objects
1011
*/
1112
export function formatMonth(
1213
locale?: string,
@@ -17,11 +18,12 @@ export function formatMonth(
1718
* Returns a function that formats a given week day number (from 0 = Sunday to 6
1819
* = Saturday) according to the specified *locale* and *format*.
1920
*
20-
* @param locale a [BCP 47 language tag](https://tools.ietf.org/html/bcp47);
21-
* defaults to U.S. English.
22-
* @param format a [weekday
23-
* format](https://tc39.es/ecma402/#datetimeformat-objects): either *narrow*,
24-
* *short*, or *long*; defaults to *short*.
21+
* @param locale a [BCP 47 language tag][1]; defaults to U.S. English.
22+
* @param format a [weekday format][2]: either *narrow*, *short*, or *long*;
23+
* defaults to *short*.
24+
*
25+
* [1]: https://tools.ietf.org/html/bcp47
26+
* [2]: https://tc39.es/ecma402/#datetimeformat-objects
2527
*/
2628
export function formatWeekday(locale?: string, format?: "long" | "short" | "narrow"): (i: number) => string;
2729

‎src/marks/text.d.ts

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -205,8 +205,8 @@ export interface TextYOptions extends Omit<TextOptions, "x"> {
205205
*
206206
* [1]: https://observablehq.com/@mbostock/number-formatting
207207
* [2]: https://observablehq.com/@mbostock/date-formatting
208-
* [3]: https://github.com/d3/d3-format
209-
* [4]: https://github.com/d3/d3-time-format
208+
* [3]: https://d3js.org/d3-format
209+
* [4]: https://d3js.org/d3-time-format
210210
*/
211211
export function text(data?: Data, options?: TextOptions): Text;
212212

‎src/plot.d.ts

Lines changed: 40 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -9,11 +9,11 @@ export interface PlotOptions extends ScaleDefaults {
99

1010
/**
1111
* The outer width of the plot in pixels, including margins. Defaults to 640.
12-
* On Observable, this can be set to the built-in
13-
* [width](https://github.com/observablehq/stdlib/blob/main/README.md#width)
14-
* for full-width responsive plots. Note: the default style has a max-width of
15-
* 100%; the plot will automatically shrink to fit even when a fixed width is
16-
* specified.
12+
* On Observable, this can be set to the built-in [width][1] for full-width
13+
* responsive plots. Note: the default style has a max-width of 100%; the plot
14+
* will automatically shrink to fit even when a fixed width is specified.
15+
*
16+
* [1]: https://github.com/observablehq/stdlib/blob/main/README.md#width
1717
*/
1818
width?: number;
1919

@@ -77,27 +77,27 @@ export interface PlotOptions extends ScaleDefaults {
7777
/**
7878
* Custom styles to override Plot’s defaults. Styles may be specified either
7979
* as a string of inline styles (*e.g.*, `"color: red;"`, in the same fashion
80-
* as assigning
81-
* [*element*.style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style))
82-
* or an object of properties (*e.g.*, `{color: "red"}`, in the same fashion
83-
* as assigning [*element*.style
84-
* properties](https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleDeclaration)).
85-
* Note that unitless numbers ([quirky
86-
* lengths](https://www.w3.org/TR/css-values-4/#deprecated-quirky-length))
87-
* such as `{padding: 20}` may not supported by some browsers; you should
88-
* instead specify a string with units such as `{padding: "20px"}`. By
89-
* default, the returned plot has a white background, a max-width of 100%, and
90-
* the system-ui font. Plot’s marks and axes default to
91-
* [currentColor](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#currentcolor_keyword),
92-
* meaning that they will inherit the surrounding content’s color. For
93-
* example, a dark theme:
80+
* as assigning [*element*.style][1]) or an object of properties (*e.g.*,
81+
* `{color: "red"}`, in the same fashion as assigning [*element*.style
82+
* properties][2]). Note that unitless numbers ([quirky lengths][3]) such as
83+
* `{padding: 20}` may not supported by some browsers; you should instead
84+
* specify a string with units such as `{padding: "20px"}`. By default, the
85+
* returned plot has a white background, a max-width of 100%, and the
86+
* system-ui font. Plot’s marks and axes default to [currentColor][4], meaning
87+
* that they will inherit the surrounding content’s color. For example, a dark
88+
* theme:
9489
*
9590
* ```js
9691
* Plot.plot({
9792
* style: "background: black; color: white;",
9893
* marks: …
9994
* })
10095
* ```
96+
*
97+
* [1]: https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style
98+
* [2]: https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleDeclaration
99+
* [3]: https://www.w3.org/TR/css-values-4/#deprecated-quirky-length
100+
* [4]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#currentcolor_keyword
101101
*/
102102
style?: string | Partial<CSSStyleDeclaration> | null;
103103

@@ -110,39 +110,41 @@ export interface PlotOptions extends ScaleDefaults {
110110
/**
111111
* The figure caption. If present, Plot wraps the generated SVG element in an
112112
* HTML figure element with a figcaption, returning the figure. To specify an
113-
* HTML caption, consider using the [`html` tagged template
114-
* literal](http://github.com/observablehq/htl); otherwise, the specified
115-
* string represents text that will be escaped as needed.
113+
* HTML caption, consider using the [`html` tagged template literal][1];
114+
* otherwise, the specified string represents text that will be escaped as
115+
* needed.
116116
*
117117
* ```js
118118
* Plot.plot({
119119
* caption: html`Figure 1. This chart has a <i>fancy</i> caption.`,
120120
* marks: …
121121
* })
122122
* ```
123+
*
124+
* [1]: https://github.com/observablehq/htl
123125
*/
124126
caption?: string | Node | null;
125127

126128
/**
127-
* The [aria-label
128-
* attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label)
129-
* on the SVG root.
129+
* The [aria-label attribute][1] on the SVG root.
130+
*
131+
* [1]: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label
130132
*/
131133
ariaLabel?: string | null;
132134

133135
/**
134-
* The [aria-description
135-
* attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-description)
136-
* on the SVG root.
136+
* The [aria-description attribute][1] on the SVG root.
137+
*
138+
* [1]: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-description
137139
*/
138140
ariaDescription?: string | null;
139141

140142
/**
141-
* The owner
142-
* [Document](https://developer.mozilla.org/en-US/docs/Web/API/Document) used
143-
* to create DOM elements. Defaults to window.document, but can be changed to
144-
* another document, say when using a virtual DOM library for server-side
145-
* rendering in Node.
143+
* The owner [Document][1] used to create DOM elements. Defaults to
144+
* window.document, but can be changed to another document, say when using a
145+
* virtual DOM library for server-side rendering in Node.
146+
*
147+
* [1]: https://developer.mozilla.org/en-US/docs/Web/API/Document
146148
*/
147149
document?: Document;
148150

@@ -184,10 +186,11 @@ export interface PlotOptions extends ScaleDefaults {
184186
* first quartile of values has a radius of 3 pixels, but no value has a
185187
* radius greater than 30 pixels.
186188
*
187-
* Plot does not currently implement a radius legend; see
188-
* [#236](https://github.com/observablehq/plot/issues/236). We recommend
189-
* either implementing one manually or labeling points so that values can be
190-
* read directly from the plot.
189+
* Plot does not currently implement a radius legend; see [#236][1]. We
190+
* recommend either implementing one manually or labeling points so that
191+
* values can be read directly from the plot.
192+
*
193+
* [1]: https://github.com/observablehq/plot/issues/236
191194
*/
192195
r?: ScaleOptions;
193196

‎src/scales.d.ts

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -579,9 +579,12 @@ export interface ScaleOptions extends ScaleDefaults {
579579
/**
580580
* How to format inputs (abstract values) for axis tick labels; one of:
581581
*
582-
* - a [d3-format](https://github.com/d3/d3-format) string for numeric scales
583-
* - a [d3-time-format](https://github.com/d3/d3-time-format) string for temporal scales
582+
* - a [d3-format][1] string for numeric scales
583+
* - a [d3-time-format][2] string for temporal scales
584584
* - a function passed a tick *value* and *index*, returning a string
585+
*
586+
* [1]: https://d3js.org/d3-time
587+
* [2]: https://d3js.org/d3-time-format
585588
*/
586589
tickFormat?: string | ((t: any, i: number) => any) | null;
587590

‎src/transforms/stack.d.ts

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ import type {CompareFunction, Transformed} from "./basic.js";
1414
* *wiggle* offset is recommended for streamgraphs in conjunction with the
1515
* *inside-out* order. For more, see [Byron & Wattenberg][1].
1616
*
17-
* [1]: http://leebyron.com/streamgraph/
17+
* [1]: https://leebyron.com/streamgraph/
1818
*/
1919
export type StackOffsetName =
2020
| "center"
@@ -53,7 +53,7 @@ export type StackOffset = StackOffsetName | StackOffsetFunction;
5353
* The *inside-out* order is recommended for streamgraphs in conjunction with
5454
* the *wiggle* offset. For more, see [Byron & Wattenberg][1].
5555
*
56-
* [1]: http://leebyron.com/streamgraph/
56+
* [1]: https://leebyron.com/streamgraph/
5757
*/
5858
export type StackOrderName = "value" | "x" | "y" | "z" | "sum" | "appearance" | "inside-out";
5959

‎src/transforms/window.d.ts

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,9 +15,11 @@ import type {Map} from "./map.js";
1515
* - *max* - the maximum value
1616
* - *mean* - the mean (average) value
1717
* - *median* - the median value
18-
* - *variance* - the variance per [Welford’s algorithm](https://en.wikipedia.org/wiki/Algorithms_for_calculating_variance#Welford's_online_algorithm)
18+
* - *variance* - the variance per [Welford’s algorithm][1]
1919
* - *mode* - the mode (most common occurrence)
2020
* - *pXX* - the percentile value, where XX is a number in [00,99]
21+
*
22+
* [1]: https://en.wikipedia.org/wiki/Algorithms_for_calculating_variance#Welford's_online_algorithm
2123
*/
2224
export type WindowReducerName =
2325
| "difference" // specific to window

0 commit comments

Comments
 (0)