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

Update doc comments in std library #1401

Merged
merged 9 commits into from
Apr 22, 2024
Merged

Update doc comments in std library #1401

merged 9 commits into from
Apr 22, 2024

Conversation

DmitryVasilevsky
Copy link
Contributor

This PR updates doc comments in the standard library. It also adds information to the readme file describing what to put in different sections of doc comments.
This is mostly random updates to a few spots in the library rather than a consistent sweep over all functions and operation. Mostly to solicit feedback on changes needed.

@DmitryVasilevsky DmitryVasilevsky requested a review from sezna April 18, 2024 03:56
@github-actions GitHub Actions
Copy link

Change in memory usage detected by benchmark.

Memory Report for f9e9b3a

Test This Branch On Main Difference
compile core + standard lib 15968625 bytes 15964377 bytes 4248 bytes

@github-actions GitHub Actions
Copy link

Change in memory usage detected by benchmark.

Memory Report for 0146433

Test This Branch On Main Difference
compile core + standard lib 15968609 bytes 15964377 bytes 4232 bytes

@github-actions GitHub Actions
Copy link

Benchmark for 0146433

Click to view benchmark
Test Base PR %
Array append evaluation 345.7±2.66µs 337.1±1.77µs -2.49%
Array literal evaluation 192.2±0.52µs 173.6±1.53µs -9.68%
Array update evaluation 432.9±13.93µs 421.8±2.27µs -2.56%
Core + Standard library compilation 18.0±0.89ms 18.1±1.85ms +0.56%
Deutsch-Jozsa evaluation 5.1±0.05ms 5.0±0.05ms -1.96%
Large file parity evaluation 33.5±0.11ms 33.6±0.55ms +0.30%
Large input file compilation 11.8±0.60ms 11.4±0.34ms -3.39%
Large input file compilation (interpreter) 45.6±1.57ms 45.1±2.16ms -1.10%
Large nested iteration 34.1±1.13ms 33.0±0.25ms -3.23%
Perform Runtime Capabilities Analysis (RCA) on Deutsch-Jozsa sample 1498.4±40.98µs 1487.5±46.86µs -0.73%
Perform Runtime Capabilities Analysis (RCA) on large file sample 7.9±0.53ms 7.7±0.11ms -2.53%
Perform Runtime Capabilities Analysis (RCA) on teleport sample 1422.5±60.17µs 1403.5±27.08µs -1.34%
Perform Runtime Capabilities Analysis (RCA) on the core and std libraries 21.1±0.10ms 21.0±0.13ms -0.47%
Teleport evaluation 80.8±3.78µs 82.6±5.38µs +2.23%

@github-actions GitHub Actions
Copy link

Change in memory usage detected by benchmark.

Memory Report for 6c2e873

Test This Branch On Main Difference
compile core + standard lib 15968609 bytes 15964377 bytes 4232 bytes

@github-actions GitHub Actions
Copy link

Benchmark for 6c2e873

Click to view benchmark
Test Base PR %
Array append evaluation 336.7±5.88µs 337.5±7.00µs +0.24%
Array literal evaluation 173.7±1.36µs 173.6±1.51µs -0.06%
Array update evaluation 425.5±10.61µs 423.0±7.50µs -0.59%
Core + Standard library compilation 17.1±0.45ms 16.9±0.25ms -1.17%
Deutsch-Jozsa evaluation 5.1±0.07ms 5.1±0.05ms 0.00%
Large file parity evaluation 33.8±0.13ms 33.8±0.33ms 0.00%
Large input file compilation 11.3±0.20ms 11.2±0.16ms -0.88%
Large input file compilation (interpreter) 45.6±1.93ms 45.3±1.52ms -0.66%
Large nested iteration 33.0±0.43ms 33.1±1.07ms +0.30%
Perform Runtime Capabilities Analysis (RCA) on Deutsch-Jozsa sample 1495.9±31.84µs 1501.6±48.30µs +0.38%
Perform Runtime Capabilities Analysis (RCA) on large file sample 7.7±0.09ms 7.9±0.09ms +2.60%
Perform Runtime Capabilities Analysis (RCA) on teleport sample 1409.3±39.59µs 1420.2±54.83µs +0.77%
Perform Runtime Capabilities Analysis (RCA) on the core and std libraries 21.1±0.29ms 21.3±0.38ms +0.95%
Teleport evaluation 81.5±3.72µs 81.7±4.24µs +0.25%

@github-actions GitHub Actions
Copy link

Change in memory usage detected by benchmark.

Memory Report for 352efc7

Test This Branch On Main Difference
compile core + standard lib 15968609 bytes 15964377 bytes 4232 bytes

ScottCarda-MS
ScottCarda-MS approved these changes Apr 18, 2024
View reviewed changes
Copy link
Contributor

@ScottCarda-MS ScottCarda-MS left a comment

Choose a reason for hiding this comment

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

Looks good from a pass from me, but it would be easy to miss something so best to have several more reviewers.

library/std/convert.qs Outdated Show resolved Hide resolved
library/std/logical.qs Outdated Show resolved Hide resolved
library/std/math.qs Outdated Show resolved Hide resolved
library/std/math.qs Outdated Show resolved Hide resolved
library/std/math.qs Outdated Show resolved Hide resolved
@github-actions GitHub Actions
Copy link

Benchmark for 352efc7

Click to view benchmark
Test Base PR %
Array append evaluation 337.5±2.46µs 348.2±4.14µs +3.17%
Array literal evaluation 173.5±1.07µs 194.3±6.02µs +11.99%
Array update evaluation 423.4±2.29µs 434.6±4.24µs +2.65%
Core + Standard library compilation 19.4±0.89ms 19.6±0.84ms +1.03%
Deutsch-Jozsa evaluation 5.0±0.05ms 5.1±0.05ms +2.00%
Large file parity evaluation 33.7±0.10ms 33.7±0.20ms 0.00%
Large input file compilation 12.7±0.47ms 12.6±0.54ms -0.79%
Large input file compilation (interpreter) 49.8±1.30ms 48.2±1.37ms -3.21%
Large nested iteration 33.2±0.32ms 34.6±1.53ms +4.22%
Perform Runtime Capabilities Analysis (RCA) on Deutsch-Jozsa sample 1526.2±117.64µs 1535.2±126.84µs +0.59%
Perform Runtime Capabilities Analysis (RCA) on large file sample 8.0±0.12ms 8.1±0.13ms +1.25%
Perform Runtime Capabilities Analysis (RCA) on teleport sample 1447.6±133.20µs 1456.2±115.50µs +0.59%
Perform Runtime Capabilities Analysis (RCA) on the core and std libraries 22.1±0.57ms 22.0±0.24ms -0.45%
Teleport evaluation 81.6±5.30µs 83.5±4.86µs +2.33%

@DmitryVasilevsky @ScottCarda-MS
Apply suggestions from code review
68a3438 
Co-authored-by: Scott Carda <55811729+ScottCarda-MS@users.noreply.github.com>
@github-actions GitHub Actions
Copy link

Change in memory usage detected by benchmark.

Memory Report for 6186348

Test This Branch On Main Difference
compile core + standard lib 15968641 bytes 15964377 bytes 4264 bytes

@github-actions GitHub Actions
Copy link

Benchmark for 6186348

Click to view benchmark
Test Base PR %
Array append evaluation 350.1±3.90µs 342.3±2.69µs -2.23%
Array literal evaluation 198.3±4.07µs 178.6±4.24µs -9.93%
Array update evaluation 438.6±2.89µs 430.2±1.61µs -1.92%
Core + Standard library compilation 18.5±0.83ms 18.6±1.01ms +0.54%
Deutsch-Jozsa evaluation 5.0±0.06ms 5.1±0.05ms +2.00%
Large file parity evaluation 34.0±0.13ms 34.0±0.25ms 0.00%
Large input file compilation 11.9±0.46ms 12.2±0.54ms +2.52%
Large input file compilation (interpreter) 48.6±1.77ms 49.5±1.51ms +1.85%
Large nested iteration 34.4±0.56ms 34.0±0.39ms -1.16%
Perform Runtime Capabilities Analysis (RCA) on Deutsch-Jozsa sample 1515.3±96.47µs 1510.8±48.01µs -0.30%
Perform Runtime Capabilities Analysis (RCA) on large file sample 8.0±0.19ms 8.0±0.33ms 0.00%
Perform Runtime Capabilities Analysis (RCA) on teleport sample 1426.2±80.07µs 1434.3±70.16µs +0.57%
Perform Runtime Capabilities Analysis (RCA) on the core and std libraries 21.6±0.32ms 21.8±0.45ms +0.93%
Teleport evaluation 81.3±3.83µs 82.2±4.85µs +1.11%

cesarzc
cesarzc reviewed Apr 19, 2024
View reviewed changes
library/std/canon.qs Outdated Show resolved Hide resolved
@DmitryVasilevsky @cesarzc
Update library/std/canon.qs
9ffdd7b 
Co-authored-by: César Zaragoza Cortés <cesarzc@microsoft.com>
@github-actions GitHub Actions
Copy link

Change in memory usage detected by benchmark.

Memory Report for 3a496d9

Test This Branch On Main Difference
compile core + standard lib 15968665 bytes 15964377 bytes 4288 bytes

@github-actions GitHub Actions
Copy link

Benchmark for 3a496d9

Click to view benchmark
Test Base PR %
Array append evaluation 343.5±5.69µs 346.6±13.28µs +0.90%
Array literal evaluation 202.3±4.40µs 179.6±1.60µs -11.22%
Array update evaluation 427.2±2.52µs 428.0±8.69µs +0.19%
Core + Standard library compilation 17.1±0.78ms 17.2±0.46ms +0.58%
Deutsch-Jozsa evaluation 5.1±0.05ms 5.2±0.06ms +1.96%
Large file parity evaluation 33.6±0.13ms 33.9±0.59ms +0.89%
Large input file compilation 11.4±0.24ms 11.6±0.14ms +1.75%
Large input file compilation (interpreter) 44.6±0.91ms 47.0±1.43ms +5.38%
Large nested iteration 34.4±2.31ms 33.2±0.45ms -3.49%
Perform Runtime Capabilities Analysis (RCA) on Deutsch-Jozsa sample 1499.2±44.33µs 1502.9±50.93µs +0.25%
Perform Runtime Capabilities Analysis (RCA) on large file sample 7.8±0.09ms 7.8±0.13ms 0.00%
Perform Runtime Capabilities Analysis (RCA) on teleport sample 1408.4±35.24µs 1417.1±44.86µs +0.62%
Perform Runtime Capabilities Analysis (RCA) on the core and std libraries 21.4±0.19ms 21.4±0.19ms 0.00%
Teleport evaluation 81.6±3.58µs 84.1±4.18µs +3.06%

swernli
swernli approved these changes Apr 20, 2024
View reviewed changes
Copy link
Collaborator

@swernli swernli left a comment

Choose a reason for hiding this comment

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

This is great, thanks Dmitry!

library/std/canon.qs Outdated Show resolved Hide resolved
library/std/canon.qs Outdated Show resolved Hide resolved
library/std/measurement.qs Show resolved Hide resolved
library/std/measurement.qs Show resolved Hide resolved
@github-actions GitHub Actions
Copy link

Change in memory usage detected by benchmark.

Memory Report for ca373d7

Test This Branch On Main Difference
compile core + standard lib 15969785 bytes 15964377 bytes 5408 bytes

@github-actions GitHub Actions
Copy link

Benchmark for ca373d7

Click to view benchmark
Test Base PR %
Array append evaluation 334.8±2.37µs 344.7±11.91µs +2.96%
Array literal evaluation 180.7±1.67µs 199.1±0.80µs +10.18%
Array update evaluation 419.7±2.32µs 429.1±10.95µs +2.24%
Core + Standard library compilation 17.4±0.85ms 17.4±0.77ms 0.00%
Deutsch-Jozsa evaluation 5.1±0.06ms 5.2±0.13ms +1.96%
Large file parity evaluation 33.7±0.60ms 33.6±0.25ms -0.30%
Large input file compilation 11.5±0.30ms 11.6±0.43ms +0.87%
Large input file compilation (interpreter) 45.5±1.64ms 46.3±1.76ms +1.76%
Large nested iteration 32.9±0.50ms 33.3±0.15ms +1.22%
Perform Runtime Capabilities Analysis (RCA) on Deutsch-Jozsa sample 1500.7±42.43µs 1510.1±32.71µs +0.63%
Perform Runtime Capabilities Analysis (RCA) on large file sample 7.9±0.21ms 7.8±0.09ms -1.27%
Perform Runtime Capabilities Analysis (RCA) on teleport sample 1415.6±41.00µs 1421.3±29.53µs +0.40%
Perform Runtime Capabilities Analysis (RCA) on the core and std libraries 21.5±0.29ms 21.5±0.72ms 0.00%
Teleport evaluation 82.0±4.88µs 84.1±4.17µs +2.56%

@DmitryVasilevsky DmitryVasilevsky added this pull request to the merge queue Apr 22, 2024
Merged via the queue into main with commit 6393180 Apr 22, 2024
17 checks passed
@DmitryVasilevsky DmitryVasilevsky deleted the dmitryv/std-lib-docs-update branch April 22, 2024 20:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@ScottCarda-MS ScottCarda-MS ScottCarda-MS approved these changes

@sezna sezna sezna approved these changes

@swernli swernli swernli approved these changes

@cesarzc cesarzc cesarzc approved these changes

@billti billti Awaiting requested review from billti billti is a code owner

@idavis idavis Awaiting requested review from idavis idavis is a code owner

@minestarks minestarks Awaiting requested review from minestarks minestarks is a code owner

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
5 participants
@DmitryVasilevsky @cesarzc @swernli @sezna @ScottCarda-MS