Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Include MDN API documentation as class and member dartdoc comments #143

Merged
merged 25 commits into from
Feb 28, 2024
Merged

Include MDN API documentation as class and member dartdoc comments #143

merged 25 commits into from
Feb 28, 2024

Conversation

devoncarew
Copy link
Member

@devoncarew devoncarew commented Jan 14, 2024 •
edited
Loading

  • include MDN API documentation as class and member dartdoc comments

Starting as a draft PR for now - not yet ready for review.

  • I’ve reviewed the contributor guide and applied the relevant portions to this PR.
Contribution guidelines:

Note that many Dart repos have a weekly cadence for reviewing PRs - please allow for some latency before initial review feedback.

devoncarew and others added 14 commits December 28, 2023 19:19
@devoncarew
scrape MDN for API documentation
b8171f4
@devoncarew
commit the parsed documentation information
2203fb5
@devoncarew
review feedback
5fac498
@devoncarew @kevmoo
Update tool/scrape_mdn.dart
ac5e01d 
Co-authored-by: Kevin Moore <[email protected]>
@devoncarew
switch to reading from markdown files from the git repo
e7c9dd8
@devoncarew
regenerate the mdn.json file
8b5ed66
@devoncarew
update copyright
76d5828
@dependabot @devoncarew
Bump actions/stale from 8.0.0 to 9.0.0 (#132)
d1428ba 
Bumps [actions/stale](https://github.com/actions/stale) from 8.0.0 to 9.0.0.
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a href="https://github.com/actions/stale/releases">actions/stale's releases</a>.</em></p>
<blockquote>
<h2>v9.0.0</h2>
<h2>Breaking Changes</h2>
<ol>
<li>Action is now stateful: If the action ends because of <a href="https://github.com/actions/stale#operations-per-run">operations-per-run</a> then the next run will start from the first unprocessed issue skipping the issues processed during the previous run(s). The state is reset when all the issues are processed. This should be considered for scheduling workflow runs.</li>
<li>Version 9 of this action updated the runtime to Node.js 20. All scripts are now run with Node.js 20 instead of Node.js 16 and are affected by any breaking changes between Node.js 16 and 20.</li>
</ol>
<h2>What Else Changed</h2>
<ol>
<li>Performance optimization that removes unnecessary API calls by <a href="https://github.com/dsame"><code>@�dsame</code></a> <a href="https://redirect.github.com/actions/stale/pull/1033/">#1033</a> fixes <a href="https://redirect.github.com/actions/stale/issues/792">#792</a></li>
<li>Logs displaying current github API rate limit by <a href="https://github.com/dsame"><code>@�dsame</code></a> <a href="https://redirect.github.com/actions/stale/pull/1032">#1032</a> addresses <a href="https://redirect.github.com/actions/stale/issues/1029">#1029</a></li>
</ol>
<p>For more information, please read the <a href="https://github.com/actions/stale#readme">action documentation</a> and its <a href="https://github.com/actions/stale#statefulness">section about statefulness</a></p>
<h2>New Contributors</h2>
<ul>
<li><a href="https://github.com/jmeridth"><code>@�jmeridth</code></a> made their first contribution in <a href="https://redirect.github.com/actions/stale/pull/984">actions/stale#984</a></li>
<li><a href="https://github.com/nikolai-laevskii"><code>@�nikolai-laevskii</code></a> made their first contribution in <a href="https://redirect.github.com/actions/stale/pull/1020">actions/stale#1020</a></li>
<li><a href="https://github.com/dusan-trickovic"><code>@�dusan-trickovic</code></a> made their first contribution in <a href="https://redirect.github.com/actions/stale/pull/1056">actions/stale#1056</a></li>
<li><a href="https://github.com/aparnajyothi-y"><code>@�aparnajyothi-y</code></a> made their first contribution in <a href="https://redirect.github.com/actions/stale/pull/1110">actions/stale#1110</a></li>
</ul>
<p><strong>Full Changelog</strong>: <a href="https://github.com/actions/stale/compare/v8...v9.0.0">https://github.com/actions/stale/compare/v8...v9.0.0</a></p>
</blockquote>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a href="https://github.com/actions/stale/commit/28ca1036281a5e5922ead5184a1bbf96e5fc984e"><code>28ca103</code></a> Upgrade Node to v20 (<a href="https://redirect.github.com/actions/stale/issues/1110">#1110</a>)</li>
<li><a href="https://github.com/actions/stale/commit/b69b346013879cedbf50c69f572cd85439a41936"><code>b69b346</code></a> build(deps-dev): bump <code>@�types/node</code> from 18.16.18 to 20.5.1 (<a href="https://redirect.github.com/actions/stale/issues/1079">#1079</a>)</li>
<li><a href="https://github.com/actions/stale/commit/88a6f4f6cbe6984b66da80d3d448d5f0c4d1a42d"><code>88a6f4f</code></a> build(deps-dev): bump typescript from 5.1.3 to 5.2.2 (<a href="https://redirect.github.com/actions/stale/issues/1083">#1083</a>)</li>
<li><a href="https://github.com/actions/stale/commit/796531a7b39835671cd9f436d7205b1556bbcff6"><code>796531a</code></a> Merge pull request <a href="https://redirect.github.com/actions/stale/issues/1080">#1080</a> from akv-platform/fix-delete-cache</li>
<li><a href="https://github.com/actions/stale/commit/8986f6218b4935e254d5b844e8c36b4d953f2643"><code>8986f62</code></a> Don not try to delete cache if it does not exists</li>
<li><a href="https://github.com/actions/stale/commit/cab99b362baa5afbbd8c7c78234e6b071b80687d"><code>cab99b3</code></a> fix typo proceeded/processed</li>
<li><a href="https://github.com/actions/stale/commit/184e7afe930f6b5c7ce52c4b3f087692c6e912f3"><code>184e7af</code></a> Merge pull request <a href="https://redirect.github.com/actions/stale/issues/1064">#1064</a> from actions/dependabot/npm_and_yarn/typescript-esli...</li>
<li><a href="https://github.com/actions/stale/commit/523885cf3c115dcdcbed573c7eaf0f5621f124e2"><code>523885c</code></a> chore: update eslint-plugin, parser and eslint-plugin-jest</li>
<li><a href="https://github.com/actions/stale/commit/2487a1dc2b501176ca975d2d8b4d3293d72180a2"><code>2487a1d</code></a> build(deps-dev): bump <code>@�typescript-eslint/eslint-plugin</code></li>
<li><a href="https://github.com/actions/stale/commit/60c722ee97faafece819a7c41b03ec113f99717d"><code>60c722e</code></a> Merge pull request <a href="https://redirect.github.com/actions/stale/issues/1063">#1063</a> from actions/dependabot/npm_and_yarn/jest-29.6.2</li>
<li>Additional commits viewable in <a href="https://github.com/actions/stale/compare/1160a2240286f5da8ec72b1c0816ce2481aabf84...28ca1036281a5e5922ead5184a1bbf96e5fc984e">compare view</a></li>
</ul>
</details>
<br />

[![Dependabot compatibility score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=actions/stale&package-manager=github_actions&previous-version=8.0.0&new-version=9.0.0)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores)

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting `@dependabot rebase`.

---

<details>
<summary>Dependabot commands and options</summary>
<br />

You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it
- `@dependabot merge` will merge this PR after your CI passes on it
- `@dependabot squash and merge` will squash and merge this PR after your CI passes on it
- `@dependabot cancel merge` will cancel a previously requested merge and block automerging
- `@dependabot reopen` will reopen this PR if it is closed
- `@dependabot close` will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
- `@dependabot show <dependency name> ignore conditions` will show all of the ignore conditions of the specified dependency
- `@dependabot ignore this major version` will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
- `@dependabot ignore this minor version` will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
- `@dependabot ignore this dependency` will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)

</details>
@devoncarew
write additional version info into the readme (#126)
d853f69
@devoncarew
merge to main
2e2a6fd
@devoncarew
generate mdn docs as library dartdoc
80c8713
@devoncarew
re-generate package:web w/ dartdoc comments
12fb986
@devoncarew
merge to main
7ef0257
@devoncarew
update changelog
31561e7
@kevmoo
Copy link
Member

kevmoo commented Jan 14, 2024

This is SO AWESOME to see!

kevmoo
kevmoo reviewed Feb 13, 2024
View reviewed changes
CHANGELOG.md Outdated Show resolved Hide resolved
@devoncarew devoncarew marked this pull request as ready for review February 26, 2024 22:25
@devoncarew devoncarew removed their assignment Feb 27, 2024
srujzs
srujzs reviewed Feb 27, 2024
View reviewed changes
tool/generator/doc_provider.dart Show resolved Hide resolved
tool/generator/formatting.dart Show resolved Hide resolved
lib/src/dom/streams.dart Show resolved Hide resolved
lib/src/dom/streams.dart Outdated
extension type TransformStreamDefaultController._(JSObject _)
implements JSObject {
/// `Streams API`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again might not be anything we can do, but is this something we can remove?

Copy link
Member Author

@devoncarew devoncarew Feb 28, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was able to find the issue here (in the mdn scraping code), and added a test for the fix.

devoncarew
devoncarew commented Feb 28, 2024
View reviewed changes
Copy link
Member Author

@devoncarew devoncarew left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the review! Updates available in the last commit.

tool/generator/doc_provider.dart Show resolved Hide resolved
tool/generator/formatting.dart Show resolved Hide resolved
lib/src/dom/streams.dart Outdated
extension type TransformStreamDefaultController._(JSObject _)
implements JSObject {
/// `Streams API`
Copy link
Member Author

@devoncarew devoncarew Feb 28, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was able to find the issue here (in the mdn scraping code), and added a test for the fix.

lib/src/dom/streams.dart Show resolved Hide resolved
@devoncarew devoncarew merged commit 23475c0 into main Feb 28, 2024
11 checks passed
@devoncarew devoncarew deleted the generate_docs branch February 28, 2024 20:01
copybara-service bot pushed a commit to dart-lang/sdk that referenced this pull request Mar 4, 2024
@devoncarew
[deps] rev dartdoc, ecosystem, glob, http, markdown, pool, protobuf, …
d1d2919 
…shelf, sse, test, web

Revisions updated by `dart tools/rev_sdk_deps.dart`.

dartdoc (https://github.com/dart-lang/dartdoc/compare/eed92d3..cec45fb):
  cec45fbe  2024-02-29  Kallen Tu  Deprecate --resources-dir option. (dart-lang/dartdoc#3696)
  40fef4c2  2024-02-29  Sam Rawlins  In PackageBuilder._discoverLibraries, initialize newFiles outside loop. (dart-lang/dartdoc#3695)
  2760d254  2024-02-28  Sam Rawlins  Deprecate the 'include-externals' option. (dart-lang/dartdoc#3694)
  c1c0854d  2024-02-28  Sam Rawlins  Improve support for package-with-macro-application (dart-lang/dartdoc#3687)
  b28ee1f8  2024-02-28  Sam Rawlins  Deprecate the `--nodoc` Option (dart-lang/dartdoc#3690)
  7988d91f  2024-02-28  Sam Rawlins  Improve some exception messaging and comments (dart-lang/dartdoc#3691)
  a1610aa6  2024-02-28  Sam Rawlins  Bump to 8.0.6 (dart-lang/dartdoc#3692)

ecosystem (https://github.com/dart-lang/ecosystem/compare/3e4f286..49a3cbb):
  49a3cbb  2024-03-01  dependabot[bot]  Bump peter-evans/find-comment (dart-lang/ecosystem#241)
  9dd8384  2024-03-01  dependabot[bot]  Bump subosito/flutter-action from 2.12.0 to 2.13.0 (dart-lang/ecosystem#240)
  7acf3bc  2024-03-01  dependabot[bot]  Bump actions/download-artifact from 4.1.1 to 4.1.3 (dart-lang/ecosystem#242)
  5d6a0c0  2024-03-01  dependabot[bot]  Bump peter-evans/create-or-update-comment (dart-lang/ecosystem#238)
  91fcd1d  2024-03-01  dependabot[bot]  Bump actions/upload-artifact from 4.0.0 to 4.3.1 (dart-lang/ecosystem#239)

glob (https://github.com/dart-lang/glob/compare/ef5f065..379d60c):
  379d60c  2024-02-28  Kevin Moore  Require Dart 3.3 (dart-lang/glob#88)

http (https://github.com/dart-lang/http/compare/6e0a46f..470d2c3):
  470d2c3  2024-03-01  dependabot[bot]  Bump actions/cache from 4.0.0 to 4.0.1 (dart-lang/http#1145)
  a5b17e0  2024-03-01  dependabot[bot]  Bump actions/setup-java from 4.0.0 to 4.1.0 (dart-lang/http#1144)
  c1d3481  2024-02-29  Brian Quinlan  Split package:http_profile into multiple files (dart-lang/http#1143)
  69332d3  2024-02-29  Brian Quinlan  API adjustments based on cupertino_http usage experience (dart-lang/http#1141)
  199f9fa  2024-02-28  Brian Quinlan  Add a dart:io WebSocket implementation (dart-lang/http#1139)
  37fceb8  2024-02-28  Brian Quinlan  Fix incorrect documentation that used the old `isOwned` name (dart-lang/http#1140)

markdown (https://github.com/dart-lang/markdown/compare/62e3349..dd47c5d):
  dd47c5d  2024-02-28  Kevin Moore  WIP: v0.31.2 spec updates (dart-lang/markdown#591)

pool (https://github.com/dart-lang/pool/compare/782da82..c118f69):
  c118f69  2024-02-28  Kevin Moore  Latest lints, test wasm on dev channel (dart-lang/pool#81)

protobuf (https://github.com/dart-lang/protobuf/compare/ef0ab7d..b761358):
  b761358  2024-03-04  Nate Biggs  Support unknown json data and add internal set/clear field methods for generated accessors. (google/protobuf.dart#918)
  1822b81  2024-03-01  dependabot[bot]  Bump dart-lang/setup-dart from 1.5.0 to 1.6.2 (google/protobuf.dart#917)
  adab58c  2024-03-01  dependabot[bot]  Bump actions/cache from 3.3.1 to 4.0.1 (google/protobuf.dart#916)
  c283db5  2024-03-01  Ömer Sinan Ağacan  Ignore the UnmodifiableUint8ListView deprecation warning (google/protobuf.dart#915)

shelf (https://github.com/dart-lang/shelf/compare/b432620..da6a69b):
  da6a69b  2024-03-01  dependabot[bot]  Bump actions/cache from 4.0.0 to 4.0.1 (dart-lang/shelf#415)

sse (https://github.com/dart-lang/sse/compare/13ec752..b53ba14):
  b53ba14  2024-02-29  Kevin Moore  Prepare release of v4.1.5 (dart-lang/sse#105)

test (https://github.com/dart-lang/test/compare/26953ba..525f77b):
  525f77b2  2024-03-01  dependabot[bot]  Bump actions/cache from 4.0.0 to 4.0.1 (dart-lang/test#2191)
  b1041775  2024-03-01  dependabot[bot]  Bump github/codeql-action from 3.23.2 to 3.24.6 (dart-lang/test#2193)

web (https://github.com/dart-lang/web/compare/fa4280c..8870d04):
  8870d04  2024-02-29  Devon Carew  update the format of the web idl versions file (dart-lang/web#194)
  641a8df  2024-02-29  Srujan Gaddam  Add generated element constructors (dart-lang/web#185)
  5e5adc8  2024-02-28  Srujan Gaddam  Use URI instead of library name (dart-lang/web#191)
  2f00226  2024-02-28  Kevin Moore  Move IDL version details (dart-lang/web#189)
  23475c0  2024-02-28  Devon Carew  Include MDN API documentation as class and member dartdoc comments (dart-lang/web#143)

Change-Id: Ia08bf4a304a1073473d6abddb64275cca84dea13
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/355521
Auto-Submit: Devon Carew <[email protected]>
Reviewed-by: Konstantin Shcheglov <[email protected]>
Commit-Queue: Konstantin Shcheglov <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@srujzs srujzs srujzs approved these changes

@srawlins srawlins srawlins left review comments

@kevmoo kevmoo kevmoo approved these changes

Assignees
No one assigned
Labels
None yet
Projects
Next-gen JS-interop
Status: Done
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@devoncarew @kevmoo @srawlins @srujzs