Use custom JSDoc parser #257
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- always use simple hyphen before description
Doctrine is no longer maintained and doesn't support arrow functions in the type definitions.
|
I fixed and refactored this a bit. There is of course the general question whether it's smart to do this with regexes and string splitting, but I find this easier to reason about than dealing with JSDoc parsing libraries. For testing I removed whitespace (which
(I'd keep the whitespace in the output, done here just for checking. This how I spotted the bug fixed in be4f893.) -<tr>
-<td><strong>null</strong> <code>String</code></td>
-<td>None</td>
-<td><center>yes</center></td>
-<td>*</td>
-</tr>
-<tr>
-<td><strong>total</strong> <code>Number</code></td>
-<td>None</td>
-<td><center>yes</center></td>
-<td>undefined</td>
-</tr>
+<tr>
+<td><strong>format</strong> <code>(d:any)=>string</code></td>
+<td><code>d=>d</code></td>
+<td><center>no</center></td>
+<td>A function that passes the current tick value and expects a nicely formatted value in return.</td>
+</tr>
+<tr>
+<td><strong>ticks</strong> (<code>Number</code> | <code>Array<any></code> | <code>Function</code> | <code>undefined</code>)</td>
+<td>None</td>
+<td><center>no</center></td>
+<td>If this is a number, it passes that along to the <a href="https://github.com/d3/d3-scale">d3Scale.ticks</a> function. If this is an array, hardcodes the ticks to those values. If it's a function, passes along the default tick values and expects an array of tick values in return. If nothing, it uses the default ticks supplied by the D3 function.</td>
+</tr>
+<tr>
+<td><strong>tickGutter</strong> <code>Number</code></td>
+<td><code>0</code></td>
+<td><center>no</center></td>
+<td>The amount of whitespace between the start of the tick and the chart drawing area (the yRange min).</td>
+</tr>
+<tr>
+<td><strong>dx</strong> <code>Number</code></td>
+<td><code>0</code></td>
+<td><center>no</center></td>
+<td>Any optional value passed to the <code>dx</code> attribute on the text label.</td>
+</tr>
+<tr>
+<td><strong>dy</strong> <code>Number</code></td>
+<td><code>0</code></td>
+<td><center>no</center></td>
+<td>Any optional value passed to the <code>dy</code> attribute on the text label.</td>
+</tr>
+<tr>
+<td><strong>units</strong> <code>String</code></td>
+<td>None</td>
+<td><center>yes</center></td>
+<td>Whether this component should use percentage or pixel values. If <code>percentRange={true}</code> it defaults to <code>'%'</code>. Options: <code>'%'</code> or <code>'px'</code>.</td>
+</tr>
+<tr>
+<td><strong>format</strong> <code>(d:any)=>string</code></td>
+<td><code>d=>d</code></td>
+<td><center>no</center></td>
+<td>A function that passes the current tick value and expects a nicely formatted value in return.</td>
+</tr>
+<tr>
+<td><strong>ticks</strong> (<code>Number</code> | <code>Array<any></code> | <code>Function</code> | <code>undefined</code>)</td>
+<td>None</td>
+<td><center>no</center></td>
+<td>If this is a number, it passes that along to the <a href="https://github.com/d3/d3-scale">d3Scale.ticks</a> function. If this is an array, hardcodes the ticks to those values. If it's a function, passes along the default tick values and expects an array of tick values in return. If nothing, it uses the default ticks supplied by the D3 function.</td>
+</tr>
+<tr>
+<td><strong>tickGutter</strong> <code>Number</code></td>
+<td><code>0</code></td>
+<td><center>no</center></td>
+<td>The amount of whitespace between the start of the tick and the chart drawing area (the yRange min).</td>
+</tr>
+<tr>
+<td><strong>dx</strong> <code>Number</code></td>
+<td><code>0</code></td>
+<td><center>no</center></td>
+<td>Any optional value passed to the <code>dx</code> attribute on the text label.</td>
+</tr>
+<tr>
+<td><strong>dy</strong> <code>Number</code></td>
+<td><code>12</code></td>
+<td><center>no</center></td>
+<td>Any optional value passed to the <code>dy</code> attribute on the text label.</td>
+</tr>
+<tr>
+<td><strong>format</strong> <code>(d:any)=>string</code></td>
+<td><code>d=>d</code></td>
+<td><center>no</center></td>
+<td>A function that passes the current tick value and expects a nicely formatted value in return.</td>
+</tr>
+<tr>
+<td><strong>ticks</strong> (<code>Number</code> | <code>Array<any></code> | <code>Function</code> | <code>undefined</code>)</td>
+<td>None</td>
+<td><center>no</center></td>
+<td>If this is a number, it passes that along to the <a href="https://github.com/d3/d3-scale">d3Scale.ticks</a> function. If this is an array, hardcodes the ticks to those values. If it's a function, passes along the default tick values and expects an array of tick values in return. If nothing, it uses the default ticks supplied by the D3 function.</td>
+</tr>
+<tr>
+<td><strong>tickGutter</strong> <code>Number</code></td>
+<td><code>0</code></td>
+<td><center>no</center></td>
+<td>The amount of whitespace between the start of the tick and the chart drawing area (the yRange min).</td>
+</tr>
+<tr>
+<td><strong>dx</strong> <code>Number</code></td>
+<td><code>0</code></td>
+<td><center>no</center></td>
+<td>Any optional value passed to the <code>dx</code> attribute on the text label.</td>
+</tr>
+<tr>
+<td><strong>dy</strong> <code>Number</code></td>
+<td><code>0</code></td>
+<td><center>no</center></td>
+<td>Any optional value passed to the <code>dy</code> attribute on the text label.</td>
+</tr>
+<tr>
+<td><strong>units</strong> <code>String</code></td>
+<td>None</td>
+<td><center>yes</center></td>
+<td>Whether this component should use percentage or pixel values. If <code>percentRange={true}</code> it defaults to <code>'%'</code>. Options: <code>'%'</code> or <code>'px'</code>.</td>
+</tr>
+<tr>
+<td><strong>format</strong> <code>(d:any)=>string</code></td>
+<td><code>d=>d</code></td>
+<td><center>no</center></td>
+<td>A function that passes the current tick value and expects a nicely formatted value in return.</td>
+</tr>
+<tr>
+<td><strong>ticks</strong> (<code>Number</code> | <code>Array<any></code> | <code>Function</code> | <code>undefined</code>)</td>
+<td>None</td>
+<td><center>no</center></td>
+<td>If this is a number, it passes that along to the <a href="https://github.com/d3/d3-scale">d3Scale.ticks</a> function. If this is an array, hardcodes the ticks to those values. If it's a function, passes along the default tick values and expects an array of tick values in return. If nothing, it uses the default ticks supplied by the D3 function.</td>
+</tr>
+<tr>
+<td><strong>tickGutter</strong> <code>Number</code></td>
+<td><code>0</code></td>
+<td><center>no</center></td>
+<td>The amount of whitespace between the start of the tick and the chart drawing area (the xRange min).</td>
+</tr>
+<tr>
+<td><strong>dx</strong> <code>Number</code></td>
+<td><code>0</code></td>
+<td><center>no</center></td>
+<td>Any optional value passed to the <code>dx</code> attribute on the text label.</td>
+</tr>
+<tr>
+<td><strong>dy</strong> <code>Number</code></td>
+<td><code>-4</code></td>
+<td><center>no</center></td>
+<td>Any optional value passed to the <code>dy</code> attribute on the text label.</td>
+</tr>
+<tr>
+<td><strong>format</strong> <code>(d:any)=>string</code></td>
+<td><code>d=>d</code></td>
+<td><center>no</center></td>
+<td>A function that passes the current tick value and expects a nicely formatted value in return.</td>
+</tr>
+<tr>
+<td><strong>ticks</strong> (<code>Number</code> | <code>Array<any></code> | <code>Function</code>)</td>
+<td><code>4</code></td>
+<td><center>no</center></td>
+<td>If this is a number, it passes that along to the <a href="https://github.com/d3/d3-scale">d3Scale.ticks</a> function. If this is an array, hardcodes the ticks to those values. If it's a function, passes along the default tick values and expects an array of tick values in return.</td>
+</tr>
+<tr>
+<td><strong>tickGutter</strong> <code>Number</code></td>
+<td><code>0</code></td>
+<td><center>no</center></td>
+<td>The amount of whitespace between the start of the tick and the chart drawing area (the xRange min).</td>
+</tr>
+<tr>
+<td><strong>dx</strong> <code>Number</code></td>
+<td><code>0</code></td>
+<td><center>no</center></td>
+<td>Any optional value passed to the <code>dx</code> attribute on the text label.</td>
+</tr>
+<tr>
+<td><strong>dy</strong> <code>Number</code></td>
+<td><code>-3</code></td>
+<td><center>no</center></td>
+<td>Any optional value passed to the <code>dy</code> attribute on the text label.</td>
+</tr>
+<tr>
+<td><strong>charPixelWidth</strong> <code>Number</code></td>
+<td><code>7.25</code></td>
+<td><center>no</center></td>
+<td>Used to calculate the widest label length to offset labels. Adjust if the automatic tick length doesn't look right because you have a bigger font (or just set <code>tickMarkLength</code> to a pixel value).</td>
+</tr>
+<tr>
+<td><strong>units</strong> <code>String</code></td>
+<td>None</td>
+<td><center>yes</center></td>
+<td>Whether this component should use percentage or pixel values. If <code>percentRange={true}</code> it defaults to <code>'%'</code>. Options: <code>'%'</code> or <code>'px'</code>.</td>
+</tr>
+<tr>
+<td><strong>format</strong> <code>(d:any)=>string</code></td>
+<td><code>d=>d</code></td>
+<td><center>no</center></td>
+<td>A function that passes the current tick value and expects a nicely formatted value in return.</td>
+</tr>
+<tr>
+<td><strong>ticks</strong> (<code>Number</code> | <code>Array<any></code> | <code>Function</code>)</td>
+<td><code>4</code></td>
+<td><center>no</center></td>
+<td>If this is a number, it passes that along to the <a href="https://github.com/d3/d3-scale">d3Scale.ticks</a> function. If this is an array, hardcodes the ticks to those values. If it's a function, passes along the default tick values and expects an array of tick values in return.</td>
+</tr>
+<tr>
+<td><strong>tickGutter</strong> <code>Number</code></td>
+<td><code>0</code></td>
+<td><center>no</center></td>
+<td>The amount of whitespace between the start of the tick and the chart drawing area (the xRange min).</td>
+</tr>
+<tr>
+<td><strong>dx</strong> <code>Number</code></td>
+<td><code>0</code></td>
+<td><center>no</center></td>
+<td>Any optional value passed to the <code>dx</code> attribute on the text label.</td>
+</tr>
+<tr>
+<td><strong>dy</strong> <code>Number</code></td>
+<td><code>0</code></td>
+<td><center>no</center></td>
+<td>Any optional value passed to the <code>dy</code> attribute on the text label.</td>
+</tr>
+<tr>
+<td><strong>charPixelWidth</strong> <code>Number</code></td>
+<td><code>7.25</code></td>
+<td><center>no</center></td>
+<td>Used to calculate the widest label length to offset labels. Adjust if the automatic tick length doesn't look right because you have a bigger font (or just set <code>tickMarkLength</code> to a pixel value).</td>
+</tr>
+<tr>
+<td><strong>format</strong> <code>(d:any)=>string</code></td>
+<td><code>d=>d</code></td>
+<td><center>no</center></td>
+<td>A function that passes the current tick value and expects a nicely formatted value in return.</td>
+</tr>
+<tr>
+<td><strong>ticks</strong> (<code>Number</code> | <code>Array<any></code> | <code>Function</code>)</td>
+<td><code>4</code></td>
+<td><center>no</center></td>
+<td>If this is a number, it passes that along to the <a href="https://github.com/d3/d3-scale">d3Scale.ticks</a> function. If this is an array, hardcodes the ticks to those values. If it's a function, passes along the default tick values and expects an array of tick values in return.</td>
+</tr>
+<tr>
+<td><strong>tickGutter</strong> <code>Number</code></td>
+<td><code>5</code></td>
+<td><center>no</center></td>
+<td>The amount of whitespace between the start of the tick and the chart drawing area (the xRange min).</td>
+</tr>
+<tr>
+<td><strong>dx</strong> <code>Number</code></td>
+<td><code>0</code></td>
+<td><center>no</center></td>
+<td>Any optional value passed to the <code>dx</code> attribute on the text label.</td>
+</tr>
+<tr>
+<td><strong>dy</strong> <code>Number</code></td>
+<td><code>-3</code></td>
+<td><center>no</center></td>
+<td>Any optional value passed to the <code>dy</code> attribute on the text label.</td>
+</tr>
+<tr>
+<td><strong>charPixelWidth</strong> <code>Number</code></td>
+<td><code>7.25</code></td>
+<td><center>no</center></td>
+<td>Used to calculate the widest label length to offset labels. Adjust if the automatic tick length doesn't look right because you have a bigger font (or just set <code>tickMarkLength</code> to a pixel value).</td>
+</tr>
+<tr>
+<td><strong>units</strong> <code>String</code></td>
+<td>None</td>
+<td><center>yes</center></td>
+<td>Whether this component should use percentage or pixel values. If <code>percentRange={true}</code> it defaults to <code>'%'</code>. Options: <code>'%'</code> or <code>'px'</code>.</td>
+</tr>
+<tr>
+<td><strong>format</strong> <code>(d:any)=>string</code></td>
+<td><code>d=>d</code></td>
+<td><center>no</center></td>
+<td>A function that passes the current tick value and expects a nicely formatted value in return.</td>
+</tr>
+<tr>
+<td><strong>ticks</strong> (<code>Number</code> | <code>Array<any></code> | <code>Function</code>)</td>
+<td><code>4</code></td>
+<td><center>no</center></td>
+<td>If this is a number, it passes that along to the <a href="https://github.com/d3/d3-scale">d3Scale.ticks</a> function. If this is an array, hardcodes the ticks to those values. If it's a function, passes along the default tick values and expects an array of tick values in return.</td>
+</tr>
+<tr>
+<td><strong>tickGutter</strong> <code>Number</code></td>
+<td><code>5</code></td>
+<td><center>no</center></td>
+<td>The amount of whitespace between the start of the tick and the chart drawing area (the xRange min).</td>
+</tr>
+<tr>
+<td><strong>dx</strong> <code>Number</code></td>
+<td><code>0</code></td>
+<td><center>no</center></td>
+<td>Any optional value passed to the <code>dx</code> attribute on the text label.</td>
+</tr>
+<tr>
+<td><strong>dy</strong> <code>Number</code></td>
+<td><code>0</code></td>
+<td><center>no</center></td>
+<td>Any optional value passed to the <code>dy</code> attribute on the text label.</td>
+</tr>
+<tr>
+<td><strong>charPixelWidth</strong> <code>Number</code></td>
+<td><code>7.25</code></td>
+<td><center>no</center></td>
+<td>Used to calculate the widest label length to offset labels. Adjust if the automatic tick length doesn't look right because you have a bigger font (or just set <code>tickMarkLength</code> to a pixel value).</td>
+</tr>
-<td><strong>getTitle</strong> <code>Function</code></td>
+<td><strong>getTitle</strong> (<code>Function</code> | <code>undefined</code>)</td>
-<td><strong>labels</strong> <code>Array</code></td>
+<td><strong>labels</strong> <code>Array<Object></code></td>
-<td>= - An accessor function to return the label field on your objects in the <code>labels</code> array.</td>
+<td>An accessor function to return the label field on your objects in the <code>labels</code> array.</td>
-<td><strong>features</strong> (<code>undefined</code> | <code>undefined</code>)</td>
+<td><strong>features</strong> (<code>Array<Object></code> | <code>undefined</code>)</td>
-<td><strong>features</strong> (<code>undefined</code> | <code>undefined</code>)</td>
+<td><strong>features</strong> (<code>Array<Object></code> | <code>undefined</code>)</td>
-<td><strong>features</strong> (<code>undefined</code> | <code>undefined</code>)</td>
+<td><strong>features</strong> (<code>Array<Object></code> | <code>undefined</code>)</td>
-<td><strong>features</strong> (<code>undefined</code> | <code>undefined</code>)</td>
+<td><strong>features</strong> (<code>Array<Object></code> | <code>undefined</code>)</td>
-<td><strong>features</strong> (<code>undefined</code> | <code>undefined</code>)</td>
+<td><strong>features</strong> (<code>Array<Object></code> | <code>undefined</code>)</td>
-<td><strong>features</strong> (<code>undefined</code> | <code>undefined</code>)</td>
+<td><strong>features</strong> (<code>Array<Object></code> | <code>undefined</code>)</td>
-<td><strong>dataset</strong> (<code>undefined</code> | <code>undefined</code>)</td>
+<td><strong>dataset</strong> (<code>Array<Object></code> | <code>undefined</code>)</td>
-<td><strong>dataset</strong> (<code>undefined</code> | <code>undefined</code>)</td>
+<td><strong>dataset</strong> (<code>Array<Object></code> | <code>undefined</code>)</td>
-<td><code>d=>'rgba(0, 0, 0, .2)'</code></td>
+<td><code>d=>'rgba(0,0,0,.2)'</code></td>
-<td><strong>linkSort</strong> (<code>Function</code> | <code>undefined</code>)</td>
+<td><strong>linkSort</strong> (<code>Function</code> | <code>null</code>)</td>
-<td><strong>dataset</strong> (<code>undefined</code> | <code>undefined</code>)</td>
+<td><strong>dataset</strong> (<code>Array<Object></code> | <code>undefined</code>)</td>
-<td><strong>dataset</strong> (<code>undefined</code> | <code>undefined</code>)</td>
+<td><strong>dataset</strong> (<code>Array<Object></code> | <code>undefined</code>)</td> |
mhkeller
reviewed
Mar 26, 2025
| @@ -19,7 +19,7 @@ | |||
| /** @type {Number} [spacing=1.5] - Spacing, in pixels, between each circle. */ | |||
| export let spacing = 1.5; | |||
|
|
|||
| /** @type {Function} [getTitle] — An accessor function to get the field on the data element to display as a hover label. Mostly useful for debugging, needs better styling for production. */ | |||
| /** @type {Function|undefined} [getTitle] - An accessor function to get the field on the data element to display as a hover label. Mostly useful for debugging, needs better styling for production. */ | |||
There was a problem hiding this comment.
If a param is optional with the square brackets, doesn't that imply that it could be undefined?
There was a problem hiding this comment.
I probably wasn't consistent with this before since I see that's how I had the getTitle propr in Beeswarm.svelte
|
Thanks a bunch for doing this. I'll merge this in and we can deal with the |
rgieseke
added a commit
to rgieseke/layercake
that referenced
this pull request
Mar 26, 2025
Parsing the JSDoc comments was fixed in mhkeller#257
mhkeller
added a commit
that referenced
this pull request
May 11, 2025
* Add Playwright snapshot tests for components * Add screenshot tests for examples Also updates slow force layout examples to be tested. * Add snapshot test for component property tables in docs * Update documentation table snapshots Parsing the JSDoc comments was fixed in #257 * Add Playwright test commands to package.json * Include Playwright setup in test invocation * Run test:lib with node matrix and use extra Playwright config * Fix command * Fix version number * Fix command * reconfigure playwright test commands * add build back in * update playwright diff threshold * update test command * update threshold; add npm test init * adjust screenshot test thresholds * Use default filename for playwright screenshots * simplify update snapshot command * update calendar test snapshots * set pixel ratio only in playwright config * remove maxDiffPixels failing test had more pixels than threshold * cleanup property test code and add comment * update snapshots * Remove screenshot snapshots Moved to a separate PR. * format * Revert "format" This reverts commit 1ea1ba1. In the diff output of Playwright the whitespace matters. * ignore playwright yml snapshots in prettier formatting --------- Co-authored-by: mhkeller <code@mhkeller.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
After looking at some alternatives to Doctrine and since the JSDoc comments to be displayed are fairly regular I looked into parsing them without a library. This would require some consistency in the formatting (I changed some en-dashes to regular
-) but this should be better for consistent display in editors anyways.Let me know what you think, I think this would also be a good way forward when updating components to Svelte 5.
I did some
git diff docs/components/*.html | grep '[+\-]<t'to check for changes in the output and I think the remaining differences are hopefully only white-space related.This would close #256