Another docs pass after reviewing #1774

[ctz]

First commit is some docs improvements during review for #1774 (though they mostly predate that PR)

Second commit is a minor fix; hopefully self explanatory.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 95.97%. Comparing base (a8d3857) to head (d3904c6).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1807      +/-   ##
==========================================
- Coverage   95.97%   95.97%   -0.01%     
==========================================
  Files          85       85              
  Lines       18730    18727       -3     
==========================================
- Hits        17977    17974       -3     
  Misses        753      753              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[rustls-benchmarking]

Benchmark results

Instruction counts

Significant differences

There are no significant instruction count differences

Other differences

Click to expand

Scenario	Baseline	Candidate	Diff	Threshold
handshake_session_id_aws_lc_rs_1.2_rsa_aes_server	4035201	4017550	-17651 (-0.44%)	3.58%
handshake_tickets_aws_lc_rs_1.2_rsa_aes_server	4517779	4534925	17146 (0.38%)	2.64%
handshake_no_resume_aws_lc_rs_1.3_ecdsap384_chacha_client	8682936	8655768	-27168 (-0.31%)	0.88%
handshake_no_resume_aws_lc_rs_1.3_ecdsap384_aes_client	8654435	8680556	26121 (0.30%)	1.08%
handshake_session_id_ring_1.2_rsa_aes_client	4422248	4431781	9533 (0.22%)	0.85%
handshake_no_resume_aws_lc_rs_1.3_rsa_chacha_server	12677357	12701370	24013 (0.19%)	0.98%
handshake_tickets_aws_lc_rs_1.3_rsa_chacha_server	32708625	32648577	-60048 (-0.18%)	0.91%
handshake_tickets_ring_1.2_rsa_aes_server	4769786	4776721	6935 (0.15%)	0.64%
handshake_session_id_aws_lc_rs_1.3_ecdsap384_chacha_client	30203962	30245274	41312 (0.14%)	0.41%
transfer_no_resume_aws_lc_rs_1.2_rsa_aes_server	46219418	46277420	58002 (0.13%)	0.33%
handshake_tickets_aws_lc_rs_1.3_rsa_aes_server	32699198	32730947	31749 (0.10%)	0.59%
handshake_tickets_aws_lc_rs_1.3_ecdsap256_chacha_server	32627514	32658242	30728 (0.09%)	0.29%
handshake_tickets_aws_lc_rs_1.3_ecdsap384_aes_client	30424666	30396231	-28435 (-0.09%)	0.57%
handshake_no_resume_aws_lc_rs_1.3_rsa_aes_server	12643139	12631619	-11520 (-0.09%)	0.97%
handshake_tickets_ring_1.3_ecdsap384_chacha_server	43689407	43649666	-39741 (-0.09%)	0.22%
handshake_session_id_aws_lc_rs_1.3_ecdsap384_chacha_server	32475773	32449233	-26540 (-0.08%)	0.32%
handshake_tickets_aws_lc_rs_1.3_ecdsap384_chacha_client	30423078	30447917	24839 (0.08%)	0.39%
handshake_session_id_aws_lc_rs_1.3_rsa_aes_client	30433069	30454319	21250 (0.07%)	0.20%
transfer_no_resume_aws_lc_rs_1.3_rsa_aes_server	46313619	46284500	-29119 (-0.06%)	0.38%
handshake_tickets_aws_lc_rs_1.3_rsa_aes_client	30655938	30636932	-19006 (-0.06%)	0.32%
handshake_no_resume_aws_lc_rs_1.3_ecdsap256_chacha_client	3342687	3344608	1921 (0.06%)	0.26%
transfer_no_resume_aws_lc_rs_1.3_ecdsap384_aes_client	57991213	57958165	-33048 (-0.06%)	0.23%
handshake_tickets_aws_lc_rs_1.2_rsa_aes_client	4509878	4507350	-2528 (-0.06%)	1.06%
handshake_session_id_aws_lc_rs_1.3_ecdsap384_aes_client	30248128	30231268	-16860 (-0.06%)	0.50%
handshake_session_id_aws_lc_rs_1.3_ecdsap256_chacha_client	30234394	30250475	16081 (0.05%)	0.26%
handshake_no_resume_aws_lc_rs_1.2_rsa_aes_server	12288225	12293927	5702 (0.05%)	1.25%
handshake_session_id_aws_lc_rs_1.3_rsa_chacha_client	30426759	30412644	-14115 (-0.05%)	0.22%
handshake_session_id_aws_lc_rs_1.3_rsa_aes_server	32537580	32552396	14816 (0.05%)	0.54%
handshake_session_id_ring_1.3_ecdsap384_chacha_server	43433211	43451140	17929 (0.04%)	0.20%
handshake_tickets_aws_lc_rs_1.3_ecdsap256_aes_server	32655469	32642745	-12724 (-0.04%)	0.41%
handshake_tickets_aws_lc_rs_1.3_ecdsap384_chacha_server	32616883	32629523	12640 (0.04%)	0.55%
handshake_tickets_ring_1.3_ecdsap256_chacha_server	43652588	43669433	16845 (0.04%)	0.20%
handshake_no_resume_aws_lc_rs_1.3_ecdsap256_chacha_server	1882629	1881912	-717 (-0.04%)	0.20%
transfer_no_resume_aws_lc_rs_1.3_ecdsap384_chacha_client	92444254	92477562	33308 (0.04%)	0.20%
handshake_session_id_ring_1.2_rsa_aes_server	4334916	4333404	-1512 (-0.03%)	0.62%
handshake_no_resume_ring_1.3_ecdsap384_aes_server	13734955	13730431	-4524 (-0.03%)	0.20%
handshake_session_id_aws_lc_rs_1.2_rsa_aes_client	4177013	4175642	-1371 (-0.03%)	0.95%
handshake_tickets_aws_lc_rs_1.3_ecdsap256_chacha_client	30420240	30410620	-9620 (-0.03%)	0.42%
transfer_no_resume_aws_lc_rs_1.3_rsa_chacha_server	80436419	80461289	24870 (0.03%)	0.20%
handshake_session_id_aws_lc_rs_1.3_ecdsap256_chacha_server	32458660	32449473	-9187 (-0.03%)	0.29%
transfer_no_resume_aws_lc_rs_1.3_ecdsap384_aes_server	46254071	46264843	10772 (0.02%)	0.20%
handshake_session_id_aws_lc_rs_1.3_rsa_chacha_server	32473474	32480732	7258 (0.02%)	0.45%
handshake_no_resume_aws_lc_rs_1.3_ecdsap384_aes_server	4258089	4257154	-935 (-0.02%)	0.20%
handshake_no_resume_aws_lc_rs_1.3_ecdsap256_aes_client	3340522	3341246	724 (0.02%)	0.20%
handshake_no_resume_aws_lc_rs_1.3_ecdsap384_chacha_server	4262645	4261723	-922 (-0.02%)	0.20%
handshake_no_resume_ring_1.3_ecdsap256_aes_server	2126747	2126306	-441 (-0.02%)	0.31%
handshake_session_id_ring_1.3_rsa_aes_server	43536215	43544346	8131 (0.02%)	0.20%
handshake_session_id_ring_1.3_ecdsap256_aes_server	43545293	43537270	-8023 (-0.02%)	0.20%
handshake_tickets_ring_1.3_ecdsap384_chacha_client	42074122	42066730	-7392 (-0.02%)	0.20%
handshake_no_resume_ring_1.3_ecdsap256_aes_client	3896870	3897519	649 (0.02%)	0.21%
transfer_no_resume_ring_1.3_ecdsap256_aes_server	46265922	46273470	7548 (0.02%)	0.26%
transfer_no_resume_ring_1.3_ecdsap384_chacha_server	80344189	80331253	-12936 (-0.02%)	0.20%
handshake_session_id_ring_1.3_rsa_chacha_client	42096590	42089854	-6736 (-0.02%)	0.20%
handshake_no_resume_aws_lc_rs_1.3_ecdsap256_aes_server	1878746	1879029	283 (0.02%)	0.22%
transfer_no_resume_ring_1.3_ecdsap384_aes_server	46274374	46267433	-6941 (-0.01%)	0.20%
handshake_tickets_aws_lc_rs_1.3_ecdsap384_aes_server	32657370	32662015	4645 (0.01%)	0.27%
handshake_tickets_aws_lc_rs_1.3_ecdsap256_aes_client	30411401	30407441	-3960 (-0.01%)	0.31%
handshake_no_resume_ring_1.3_ecdsap384_aes_client	35452097	35447541	-4556 (-0.01%)	0.20%
handshake_no_resume_ring_1.3_ecdsap256_chacha_server	2128687	2128414	-273 (-0.01%)	0.38%
handshake_session_id_aws_lc_rs_1.3_ecdsap256_aes_client	30241619	30245250	3631 (0.01%)	0.33%
handshake_session_id_ring_1.3_ecdsap384_aes_server	43545582	43550536	4954 (0.01%)	0.20%
handshake_tickets_ring_1.3_rsa_chacha_server	43708741	43713599	4858 (0.01%)	0.20%
handshake_session_id_ring_1.3_ecdsap256_chacha_server	43440066	43444464	4398 (0.01%)	0.20%
handshake_tickets_ring_1.3_ecdsap256_aes_client	42149745	42153678	3933 (0.01%)	0.20%
handshake_tickets_ring_1.3_ecdsap384_aes_client	42140333	42144193	3860 (0.01%)	0.20%
handshake_no_resume_ring_1.3_rsa_aes_client	4537770	4537404	-366 (-0.01%)	0.20%
transfer_no_resume_ring_1.3_ecdsap384_aes_client	58067002	58071458	4456 (0.01%)	0.20%
handshake_tickets_ring_1.2_rsa_aes_client	4710060	4709705	-355 (-0.01%)	0.87%
handshake_session_id_ring_1.3_ecdsap384_aes_client	41971943	41974455	2512 (0.01%)	0.20%
handshake_tickets_ring_1.3_rsa_aes_server	43793941	43791328	-2613 (-0.01%)	0.20%
handshake_session_id_ring_1.3_rsa_aes_client	42169999	42172494	2495 (0.01%)	0.20%
handshake_session_id_ring_1.3_ecdsap256_chacha_client	41882725	41885035	2310 (0.01%)	0.20%
handshake_no_resume_ring_1.3_rsa_chacha_client	4546792	4546546	-246 (-0.01%)	0.20%
handshake_session_id_aws_lc_rs_1.3_ecdsap256_aes_server	32466808	32465205	-1603 (-0.00%)	0.20%
transfer_no_resume_aws_lc_rs_1.3_ecdsap256_chacha_client	92441107	92436703	-4404 (-0.00%)	0.20%
handshake_tickets_ring_1.3_rsa_aes_client	42361478	42363472	1994 (0.00%)	0.20%
handshake_session_id_ring_1.3_ecdsap256_aes_client	41966673	41964715	-1958 (-0.00%)	0.20%
handshake_no_resume_ring_1.3_ecdsap256_chacha_client	3898703	3898875	172 (0.00%)	0.28%
handshake_session_id_ring_1.3_ecdsap384_chacha_client	41896616	41898257	1641 (0.00%)	0.20%
handshake_no_resume_ring_1.3_rsa_chacha_server	12246026	12245561	-465 (-0.00%)	0.20%
handshake_tickets_ring_1.3_rsa_chacha_client	42295881	42294276	-1605 (-0.00%)	0.20%
handshake_no_resume_ring_1.3_rsa_aes_server	12236574	12236136	-438 (-0.00%)	0.20%
handshake_tickets_ring_1.3_ecdsap256_chacha_client	42084339	42085790	1451 (0.00%)	0.20%
handshake_session_id_ring_1.3_rsa_chacha_server	43442217	43441032	-1185 (-0.00%)	0.20%
transfer_no_resume_aws_lc_rs_1.3_ecdsap256_aes_client	57971356	57969846	-1510 (-0.00%)	0.20%
handshake_tickets_ring_1.3_ecdsap384_aes_server	43738798	43739916	1118 (0.00%)	0.24%
transfer_no_resume_ring_1.3_ecdsap256_chacha_client	92399829	92397470	-2359 (-0.00%)	0.20%
transfer_no_resume_aws_lc_rs_1.3_ecdsap384_chacha_server	80443213	80445208	1995 (0.00%)	0.20%
handshake_no_resume_ring_1.3_ecdsap384_chacha_server	13737270	13737583	313 (0.00%)	0.20%
transfer_no_resume_ring_1.2_rsa_aes_server	46195002	46194059	-943 (-0.00%)	0.20%
handshake_no_resume_ring_1.2_rsa_aes_client	4439916	4439828	-88 (-0.00%)	0.20%
transfer_no_resume_ring_1.3_rsa_aes_server	46273204	46274093	889 (0.00%)	0.20%
handshake_no_resume_aws_lc_rs_1.3_rsa_chacha_client	3366167	3366108	-59 (-0.00%)	0.20%
transfer_no_resume_ring_1.3_rsa_chacha_server	80341478	80342674	1196 (0.00%)	0.20%
transfer_no_resume_ring_1.3_ecdsap256_aes_client	58065845	58065194	-651 (-0.00%)	0.20%
transfer_no_resume_aws_lc_rs_1.3_rsa_aes_client	57990691	57991240	549 (0.00%)	0.20%
transfer_no_resume_aws_lc_rs_1.3_ecdsap256_aes_server	46254515	46254111	-404 (-0.00%)	0.28%
handshake_session_id_aws_lc_rs_1.3_ecdsap384_aes_server	32479581	32479311	-270 (-0.00%)	0.26%
transfer_no_resume_ring_1.3_rsa_aes_client	58066930	58067285	355 (0.00%)	0.20%
handshake_no_resume_ring_1.3_ecdsap384_chacha_client	35454651	35454829	178 (0.00%)	0.20%
transfer_no_resume_aws_lc_rs_1.3_ecdsap256_chacha_server	80444402	80444805	403 (0.00%)	0.20%
handshake_no_resume_aws_lc_rs_1.3_rsa_aes_client	3355525	3355538	13 (0.00%)	0.20%
handshake_tickets_aws_lc_rs_1.3_rsa_chacha_client	30629818	30629704	-114 (-0.00%)	0.22%
handshake_tickets_ring_1.3_ecdsap256_aes_server	43752220	43752368	148 (0.00%)	0.33%
handshake_no_resume_aws_lc_rs_1.2_rsa_aes_client	3151190	3151197	7 (0.00%)	0.20%
transfer_no_resume_ring_1.2_rsa_aes_client	57922755	57922653	-102 (-0.00%)	0.20%
handshake_no_resume_ring_1.2_rsa_aes_server	12042216	12042197	-19 (-0.00%)	0.20%
transfer_no_resume_ring_1.3_rsa_chacha_client	92401294	92401192	-102 (-0.00%)	0.20%
transfer_no_resume_ring_1.3_ecdsap384_chacha_client	92399721	92399632	-89 (-0.00%)	0.20%
transfer_no_resume_aws_lc_rs_1.2_rsa_aes_client	68431959	68431917	-42 (-0.00%)	0.20%
transfer_no_resume_ring_1.3_ecdsap256_chacha_server	80343761	80343722	-39 (-0.00%)	0.20%
transfer_no_resume_aws_lc_rs_1.3_rsa_chacha_client	92460799	92460770	-29 (-0.00%)	0.20%

Wall-time

Significant differences

There are no significant wall-time differences

Other differences

Click to expand

Scenario	Baseline	Candidate	Diff	Threshold
transfer_no_resume_aws_lc_rs_1.3_ecdsap256_aes	4.78 ms	4.73 ms	-0.06 ms (-1.20%)	5.13%
transfer_no_resume_aws_lc_rs_1.3_ecdsap384_aes	5.50 ms	5.44 ms	-0.06 ms (-1.01%)	4.01%
transfer_no_resume_aws_lc_rs_1.3_rsa_aes	5.72 ms	5.68 ms	-0.05 ms (-0.80%)	4.29%
handshake_no_resume_aws_lc_rs_1.3_ecdsap256_chacha	476.82 µs	473.20 µs	-3.63 µs (-0.76%)	3.12%
handshake_no_resume_aws_lc_rs_1.3_ecdsap256_aes	477.59 µs	473.97 µs	-3.61 µs (-0.76%)	2.89%
transfer_no_resume_ring_1.3_ecdsap256_aes	6.61 ms	6.56 ms	-0.05 ms (-0.75%)	3.49%
handshake_no_resume_ring_1.3_ecdsap256_chacha	509.52 µs	505.81 µs	-3.71 µs (-0.73%)	2.15%
transfer_no_resume_ring_1.3_rsa_aes	7.18 ms	7.13 ms	-0.05 ms (-0.70%)	2.51%
handshake_no_resume_ring_1.3_ecdsap256_aes	510.37 µs	507.59 µs	-2.78 µs (-0.54%)	2.33%
transfer_no_resume_ring_1.3_ecdsap384_aes	9.76 ms	9.71 ms	-0.05 ms (-0.54%)	2.51%
handshake_tickets_ring_1.2_rsa_aes	1.84 ms	1.83 ms	-0.01 ms (-0.50%)	1.65%
handshake_session_id_aws_lc_rs_1.3_ecdsap256_aes	5.37 ms	5.35 ms	-0.03 ms (-0.50%)	1.83%
handshake_session_id_aws_lc_rs_1.2_rsa_aes	2.17 ms	2.16 ms	-0.01 ms (-0.48%)	1.51%
transfer_no_resume_aws_lc_rs_1.2_rsa_aes	5.71 ms	5.69 ms	-0.03 ms (-0.47%)	3.40%
transfer_no_resume_aws_lc_rs_1.3_ecdsap384_chacha	13.98 ms	13.92 ms	-0.06 ms (-0.46%)	1.84%
transfer_no_resume_aws_lc_rs_1.3_ecdsap256_chacha	13.28 ms	13.22 ms	-0.06 ms (-0.46%)	1.61%
transfer_no_resume_aws_lc_rs_1.3_rsa_chacha	14.22 ms	14.16 ms	-0.06 ms (-0.43%)	1.45%
handshake_tickets_aws_lc_rs_1.3_ecdsap256_aes	5.40 ms	5.38 ms	-0.02 ms (-0.43%)	2.25%
transfer_no_resume_ring_1.3_ecdsap256_chacha	13.29 ms	13.24 ms	-0.06 ms (-0.42%)	1.85%
handshake_session_id_aws_lc_rs_1.3_rsa_aes	6.38 ms	6.35 ms	-0.03 ms (-0.41%)	1.75%
handshake_tickets_aws_lc_rs_1.2_rsa_aes	2.33 ms	2.32 ms	-0.01 ms (-0.41%)	1.66%
handshake_session_id_aws_lc_rs_1.3_ecdsap384_aes	6.08 ms	6.06 ms	-0.02 ms (-0.39%)	1.63%
handshake_session_id_aws_lc_rs_1.3_ecdsap256_chacha	5.36 ms	5.34 ms	-0.02 ms (-0.39%)	1.80%
transfer_no_resume_ring_1.3_rsa_chacha	13.87 ms	13.82 ms	-0.05 ms (-0.38%)	1.56%
transfer_no_resume_ring_1.2_rsa_aes	7.09 ms	7.06 ms	-0.03 ms (-0.37%)	3.11%
transfer_no_resume_ring_1.3_ecdsap384_chacha	16.45 ms	16.39 ms	-0.06 ms (-0.37%)	1.66%
handshake_session_id_ring_1.2_rsa_aes	1.75 ms	1.74 ms	-0.01 ms (-0.33%)	2.70%
handshake_tickets_aws_lc_rs_1.3_rsa_aes	6.40 ms	6.37 ms	-0.02 ms (-0.32%)	1.86%
handshake_no_resume_ring_1.3_rsa_aes	1.08 ms	1.08 ms	-0.00 ms (-0.30%)	1.00%
handshake_no_resume_aws_lc_rs_1.3_ecdsap384_chacha	1.18 ms	1.18 ms	-0.00 ms (-0.29%)	1.25%
handshake_session_id_aws_lc_rs_1.3_rsa_chacha	6.36 ms	6.34 ms	-0.02 ms (-0.27%)	1.50%
handshake_tickets_aws_lc_rs_1.3_ecdsap384_aes	6.12 ms	6.10 ms	-0.02 ms (-0.27%)	1.78%
handshake_session_id_aws_lc_rs_1.3_ecdsap384_chacha	6.05 ms	6.04 ms	-0.02 ms (-0.27%)	1.51%
handshake_no_resume_ring_1.3_rsa_chacha	1.09 ms	1.09 ms	-0.00 ms (-0.23%)	1.00%
handshake_no_resume_aws_lc_rs_1.2_rsa_aes	1.36 ms	1.36 ms	-0.00 ms (-0.21%)	1.13%
handshake_no_resume_aws_lc_rs_1.3_rsa_chacha	1.41 ms	1.40 ms	-0.00 ms (-0.20%)	1.00%
handshake_tickets_aws_lc_rs_1.3_ecdsap384_chacha	6.10 ms	6.09 ms	-0.01 ms (-0.20%)	2.02%
handshake_no_resume_aws_lc_rs_1.3_ecdsap384_aes	1.19 ms	1.19 ms	-0.00 ms (-0.20%)	1.13%
handshake_tickets_aws_lc_rs_1.3_ecdsap256_chacha	5.39 ms	5.38 ms	-0.01 ms (-0.20%)	2.43%
handshake_no_resume_ring_1.2_rsa_aes	1.08 ms	1.07 ms	-0.00 ms (-0.20%)	1.08%
handshake_session_id_ring_1.3_rsa_aes	7.57 ms	7.56 ms	-0.01 ms (-0.16%)	1.68%
handshake_no_resume_aws_lc_rs_1.3_rsa_aes	1.41 ms	1.41 ms	-0.00 ms (-0.15%)	1.00%
handshake_tickets_ring_1.3_ecdsap256_aes	6.96 ms	6.95 ms	-0.01 ms (-0.14%)	1.87%
handshake_session_id_ring_1.3_ecdsap256_aes	6.94 ms	6.93 ms	-0.01 ms (-0.12%)	1.78%
handshake_tickets_ring_1.3_ecdsap256_chacha	6.91 ms	6.90 ms	-0.01 ms (-0.12%)	2.05%
handshake_no_resume_ring_1.3_ecdsap384_chacha	3.67 ms	3.66 ms	-0.00 ms (-0.11%)	1.00%
handshake_session_id_ring_1.3_rsa_chacha	7.52 ms	7.52 ms	-0.01 ms (-0.11%)	2.03%
handshake_session_id_ring_1.3_ecdsap256_chacha	6.90 ms	6.89 ms	-0.01 ms (-0.10%)	1.78%
handshake_tickets_aws_lc_rs_1.3_rsa_chacha	6.38 ms	6.38 ms	-0.01 ms (-0.08%)	2.11%
handshake_tickets_ring_1.3_ecdsap384_aes	10.11 ms	10.10 ms	-0.01 ms (-0.06%)	1.48%
handshake_session_id_ring_1.3_ecdsap384_chacha	10.04 ms	10.03 ms	-0.01 ms (-0.06%)	1.49%
handshake_tickets_ring_1.3_rsa_chacha	7.54 ms	7.54 ms	-0.00 ms (-0.05%)	1.96%
handshake_session_id_ring_1.3_ecdsap384_aes	10.08 ms	10.07 ms	-0.00 ms (-0.04%)	1.49%
handshake_tickets_ring_1.3_rsa_aes	7.59 ms	7.58 ms	-0.00 ms (-0.04%)	1.70%
handshake_tickets_ring_1.3_ecdsap384_chacha	10.06 ms	10.05 ms	-0.00 ms (-0.03%)	1.80%
handshake_no_resume_ring_1.3_ecdsap384_aes	3.66 ms	3.66 ms	-0.00 ms (-0.01%)	1.00%

Additional information

Historical results

Checkout details:

• Base repo: https://github.com/rustls/rustls.git
• Base branch: main (a8d3857)
• Candidate repo: https://github.com/rustls/rustls.git
• Candidate branch: jbp-pr1774-nits (d3904c6)