examples: consistently document example program purpose

[cpu]

Adding an introductory Rustdoc comment to new examples was review feedback delivered in #1583, but we're not doing this consistently for all existing examples (💔).

This branch addresses this oversight that by adding short intro documentation to simple_0rtt_client.rs, and the two MIO examples (tlsclient-mio.rs and tlsserver-mio.rs).

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (b245ffa) 95.90% compared to head (e5b804f) 95.90%.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1693   +/-   ##
=======================================
  Coverage   95.90%   95.90%           
=======================================
  Files          78       78           
  Lines       16211    16211           
=======================================
  Hits        15547    15547           
  Misses        664      664           

☔ 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	4055358	4154201	98843 (2.44%)	4.24%
handshake_tickets_aws_lc_rs_1.2_rsa_aes_server	4610069	4637507	27438 (0.60%)	2.44%
handshake_no_resume_aws_lc_rs_1.2_rsa_aes_server	12379071	12344582	-34489 (-0.28%)	0.68%
handshake_no_resume_aws_lc_rs_1.3_rsa_chacha_server	12742569	12776052	33483 (0.26%)	0.96%
handshake_tickets_aws_lc_rs_1.3_rsa_chacha_server	33598044	33513499	-84545 (-0.25%)	0.68%
handshake_session_id_aws_lc_rs_1.3_rsa_aes_server	33302920	33258193	-44727 (-0.13%)	0.47%
transfer_no_resume_aws_lc_rs_1.2_rsa_aes_server	57097316	57162099	64783 (0.11%)	0.35%
handshake_no_resume_aws_lc_rs_1.3_rsa_aes_server	12739155	12748721	9566 (0.08%)	0.68%
handshake_session_id_aws_lc_rs_1.3_rsa_chacha_server	33267163	33249078	-18085 (-0.05%)	0.66%
handshake_tickets_aws_lc_rs_1.3_rsa_aes_server	33563406	33545659	-17747 (-0.05%)	0.35%
handshake_session_id_aws_lc_rs_1.3_ecdsa_chacha_client	30983950	30972036	-11914 (-0.04%)	0.20%
handshake_no_resume_aws_lc_rs_1.3_ecdsa_aes_client	5209883	5207964	-1919 (-0.04%)	0.20%
transfer_no_resume_aws_lc_rs_1.3_rsa_chacha_server	91340288	91307927	-32361 (-0.04%)	0.20%
handshake_no_resume_ring_1.3_ecdsa_chacha_client	14416154	14420230	4076 (0.03%)	0.20%
handshake_tickets_aws_lc_rs_1.3_ecdsa_chacha_client	31148267	31156502	8235 (0.03%)	0.20%
transfer_no_resume_aws_lc_rs_1.3_rsa_aes_server	57137443	57128533	-8910 (-0.02%)	0.29%
handshake_tickets_ring_1.3_ecdsa_chacha_client	42220738	42216765	-3973 (-0.01%)	0.20%
handshake_no_resume_aws_lc_rs_1.3_ecdsa_chacha_client	5213742	5214205	463 (0.01%)	0.20%
handshake_no_resume_aws_lc_rs_1.2_rsa_aes_client	3173593	3173818	225 (0.01%)	0.20%
handshake_no_resume_ring_1.3_ecdsa_aes_server	2133235	2133371	136 (0.01%)	0.20%
transfer_no_resume_ring_1.3_ecdsa_chacha_client	92364939	92370799	5860 (0.01%)	0.20%
handshake_tickets_ring_1.3_ecdsa_aes_client	42252106	42249507	-2599 (-0.01%)	0.20%
handshake_session_id_ring_1.3_ecdsa_aes_client	42072567	42070055	-2512 (-0.01%)	0.20%
handshake_no_resume_ring_1.2_rsa_aes_client	4442062	4442321	259 (0.01%)	0.20%
handshake_tickets_aws_lc_rs_1.2_rsa_aes_client	4515856	4515593	-263 (-0.01%)	0.20%
handshake_session_id_aws_lc_rs_1.3_ecdsa_aes_client	30986853	30988422	1569 (0.01%)	0.20%
handshake_no_resume_aws_lc_rs_1.3_ecdsa_chacha_server	2056691	2056792	101 (0.00%)	0.20%
handshake_tickets_aws_lc_rs_1.3_ecdsa_aes_client	31164161	31165663	1502 (0.00%)	0.20%
handshake_session_id_ring_1.3_ecdsa_chacha_client	42027529	42025551	-1978 (-0.00%)	0.20%
handshake_session_id_ring_1.2_rsa_aes_client	4450397	4450189	-208 (-0.00%)	0.20%
handshake_no_resume_aws_lc_rs_1.3_rsa_chacha_client	3387900	3388054	154 (0.00%)	0.20%
handshake_session_id_aws_lc_rs_1.2_rsa_aes_client	4177319	4177134	-185 (-0.00%)	0.20%
handshake_no_resume_ring_1.3_rsa_chacha_client	4548330	4548528	198 (0.00%)	0.20%
handshake_no_resume_aws_lc_rs_1.3_ecdsa_aes_server	2052395	2052483	88 (0.00%)	0.20%
transfer_no_resume_aws_lc_rs_1.3_ecdsa_aes_client	57964723	57967143	2420 (0.00%)	0.20%
handshake_no_resume_ring_1.3_ecdsa_aes_client	14417111	14417700	589 (0.00%)	0.20%
handshake_no_resume_ring_1.3_rsa_aes_client	4538311	4538447	136 (0.00%)	0.20%
handshake_tickets_ring_1.2_rsa_aes_client	4739781	4739642	-139 (-0.00%)	0.20%
transfer_no_resume_aws_lc_rs_1.3_rsa_chacha_client	92431340	92433877	2537 (0.00%)	0.20%
handshake_no_resume_aws_lc_rs_1.3_rsa_aes_client	3377271	3377359	88 (0.00%)	0.20%
handshake_tickets_ring_1.2_rsa_aes_server	4859178	4859300	122 (0.00%)	0.20%
handshake_session_id_ring_1.2_rsa_aes_server	4419296	4419385	89 (0.00%)	0.20%
transfer_no_resume_ring_1.2_rsa_aes_client	57841099	57840476	-623 (-0.00%)	0.20%
transfer_no_resume_aws_lc_rs_1.3_ecdsa_chacha_client	92432883	92431973	-910 (-0.00%)	0.20%
transfer_no_resume_ring_1.3_rsa_aes_client	57941311	57940743	-568 (-0.00%)	0.20%
handshake_session_id_aws_lc_rs_1.3_ecdsa_aes_server	33281202	33281517	315 (0.00%)	0.20%
handshake_no_resume_ring_1.3_rsa_aes_server	12240655	12240767	112 (0.00%)	0.20%
transfer_no_resume_ring_1.3_ecdsa_aes_client	57926333	57925803	-530 (-0.00%)	0.20%
handshake_no_resume_ring_1.3_ecdsa_chacha_server	2136008	2135989	-19 (-0.00%)	0.20%
handshake_tickets_aws_lc_rs_1.3_ecdsa_aes_server	33534470	33534250	-220 (-0.00%)	0.20%
handshake_tickets_ring_1.3_ecdsa_aes_server	43906583	43906304	-279 (-0.00%)	0.20%
transfer_no_resume_aws_lc_rs_1.3_rsa_aes_client	57974092	57973866	-226 (-0.00%)	0.20%
handshake_session_id_aws_lc_rs_1.3_ecdsa_chacha_server	33262707	33262835	128 (0.00%)	0.20%
handshake_tickets_ring_1.3_rsa_chacha_server	43857909	43858063	154 (0.00%)	0.20%
handshake_tickets_ring_1.3_ecdsa_chacha_server	43866437	43866589	152 (0.00%)	0.20%
handshake_tickets_aws_lc_rs_1.3_rsa_aes_client	31369696	31369803	107 (0.00%)	0.20%
handshake_tickets_aws_lc_rs_1.3_ecdsa_chacha_server	33546520	33546409	-111 (-0.00%)	0.20%
handshake_session_id_ring_1.3_rsa_aes_client	42252426	42252323	-103 (-0.00%)	0.20%
transfer_no_resume_ring_1.3_rsa_chacha_client	92380772	92380565	-207 (-0.00%)	0.20%
handshake_session_id_ring_1.3_rsa_chacha_server	43608075	43608165	90 (0.00%)	0.20%
transfer_no_resume_aws_lc_rs_1.3_ecdsa_chacha_server	91340342	91340169	-173 (-0.00%)	0.20%
transfer_no_resume_ring_1.3_ecdsa_aes_server	57081684	57081576	-108 (-0.00%)	0.20%
handshake_session_id_ring_1.3_rsa_chacha_client	42205527	42205453	-74 (-0.00%)	0.20%
handshake_tickets_ring_1.3_rsa_chacha_client	42397760	42397690	-70 (-0.00%)	0.20%
handshake_tickets_aws_lc_rs_1.3_rsa_chacha_client	31351549	31351501	-48 (-0.00%)	0.20%
handshake_tickets_ring_1.3_rsa_aes_server	43898241	43898175	-66 (-0.00%)	0.20%
transfer_no_resume_ring_1.2_rsa_aes_server	56966552	56966628	76 (0.00%)	0.20%
transfer_no_resume_ring_1.3_ecdsa_chacha_server	91246108	91246223	115 (0.00%)	0.20%
handshake_session_id_ring_1.3_ecdsa_aes_server	43681135	43681183	48 (0.00%)	0.20%
transfer_no_resume_ring_1.3_rsa_aes_server	57102675	57102616	-59 (-0.00%)	0.20%
handshake_session_id_aws_lc_rs_1.3_rsa_aes_client	31180310	31180278	-32 (-0.00%)	0.20%
transfer_no_resume_aws_lc_rs_1.2_rsa_aes_client	68408674	68408604	-70 (-0.00%)	0.20%
handshake_session_id_ring_1.3_ecdsa_chacha_server	43615318	43615278	-40 (-0.00%)	0.20%
transfer_no_resume_aws_lc_rs_1.3_ecdsa_aes_server	57175749	57175701	-48 (-0.00%)	0.20%
handshake_session_id_aws_lc_rs_1.3_rsa_chacha_client	31131580	31131554	-26 (-0.00%)	0.20%
handshake_no_resume_ring_1.2_rsa_aes_server	12044918	12044910	-8 (-0.00%)	0.20%
handshake_tickets_ring_1.3_rsa_aes_client	42432924	42432952	28 (0.00%)	0.20%
transfer_no_resume_ring_1.3_rsa_chacha_server	91266819	91266877	58 (0.00%)	0.20%
handshake_no_resume_ring_1.3_rsa_chacha_server	12250946	12250952	6 (0.00%)	0.20%
handshake_session_id_ring_1.3_rsa_aes_server	43674237	43674233	-4 (-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_ecdsa_aes	5.10 ms	5.19 ms	0.08 ms (1.66%)	5.15%
transfer_no_resume_aws_lc_rs_1.2_rsa_aes	5.88 ms	5.95 ms	0.07 ms (1.23%)	4.49%
transfer_no_resume_aws_lc_rs_1.3_rsa_aes	5.87 ms	5.94 ms	0.07 ms (1.22%)	4.41%
transfer_no_resume_ring_1.3_ecdsa_aes	7.46 ms	7.53 ms	0.07 ms (0.94%)	3.55%
transfer_no_resume_ring_1.3_rsa_aes	7.30 ms	7.36 ms	0.06 ms (0.77%)	3.75%
transfer_no_resume_ring_1.2_rsa_aes	7.22 ms	7.28 ms	0.05 ms (0.76%)	3.81%
handshake_tickets_aws_lc_rs_1.2_rsa_aes	2.24 ms	2.26 ms	0.02 ms (0.71%)	1.04%
handshake_no_resume_aws_lc_rs_1.3_ecdsa_chacha	653.53 µs	657.19 µs	3.66 µs (0.56%)	2.55%
handshake_no_resume_aws_lc_rs_1.3_ecdsa_aes	654.85 µs	658.37 µs	3.52 µs (0.54%)	2.58%
transfer_no_resume_ring_1.3_ecdsa_chacha	14.22 ms	14.30 ms	0.07 ms (0.52%)	1.81%
transfer_no_resume_aws_lc_rs_1.3_ecdsa_chacha	13.59 ms	13.66 ms	0.07 ms (0.50%)	1.89%
transfer_no_resume_aws_lc_rs_1.3_rsa_chacha	14.35 ms	14.42 ms	0.07 ms (0.50%)	1.64%
handshake_tickets_aws_lc_rs_1.3_ecdsa_aes	5.60 ms	5.62 ms	0.03 ms (0.47%)	1.27%
handshake_session_id_aws_lc_rs_1.2_rsa_aes	2.07 ms	2.08 ms	0.01 ms (0.45%)	1.40%
transfer_no_resume_ring_1.3_rsa_chacha	14.06 ms	14.12 ms	0.06 ms (0.42%)	1.77%
handshake_tickets_aws_lc_rs_1.3_ecdsa_chacha	5.58 ms	5.60 ms	0.02 ms (0.37%)	1.00%
handshake_session_id_aws_lc_rs_1.3_rsa_aes	6.38 ms	6.40 ms	0.02 ms (0.37%)	1.00%
handshake_session_id_aws_lc_rs_1.3_ecdsa_aes	5.57 ms	5.58 ms	0.02 ms (0.35%)	1.02%
handshake_session_id_aws_lc_rs_1.3_rsa_chacha	6.36 ms	6.38 ms	0.02 ms (0.33%)	1.00%
handshake_tickets_aws_lc_rs_1.3_rsa_aes	6.41 ms	6.43 ms	0.02 ms (0.30%)	1.07%
handshake_session_id_aws_lc_rs_1.3_ecdsa_chacha	5.55 ms	5.56 ms	0.02 ms (0.30%)	1.00%
handshake_tickets_aws_lc_rs_1.3_rsa_chacha	6.39 ms	6.41 ms	0.02 ms (0.27%)	1.06%
handshake_tickets_ring_1.2_rsa_aes	1.78 ms	1.79 ms	0.00 ms (0.25%)	1.29%
handshake_no_resume_ring_1.3_rsa_aes	1.08 ms	1.08 ms	0.00 ms (0.22%)	1.63%
handshake_session_id_ring_1.2_rsa_aes	1.70 ms	1.70 ms	0.00 ms (0.21%)	1.34%
handshake_no_resume_ring_1.3_ecdsa_chacha	1.26 ms	1.27 ms	0.00 ms (0.19%)	1.00%
handshake_no_resume_ring_1.2_rsa_aes	1.07 ms	1.07 ms	0.00 ms (0.17%)	1.38%
handshake_no_resume_aws_lc_rs_1.3_rsa_chacha	1.40 ms	1.40 ms	0.00 ms (0.15%)	1.02%
handshake_no_resume_ring_1.3_rsa_chacha	1.09 ms	1.09 ms	0.00 ms (0.15%)	1.50%
handshake_no_resume_aws_lc_rs_1.3_rsa_aes	1.41 ms	1.41 ms	0.00 ms (0.14%)	1.00%
handshake_session_id_ring_1.3_ecdsa_aes	7.63 ms	7.64 ms	0.01 ms (0.12%)	1.00%
handshake_session_id_ring_1.3_rsa_aes	7.51 ms	7.52 ms	0.01 ms (0.09%)	1.00%
handshake_tickets_ring_1.3_rsa_chacha	7.50 ms	7.49 ms	-0.01 ms (-0.09%)	1.00%
handshake_tickets_ring_1.3_ecdsa_chacha	7.62 ms	7.61 ms	-0.01 ms (-0.09%)	1.00%
handshake_no_resume_ring_1.3_ecdsa_aes	1.27 ms	1.27 ms	0.00 ms (0.06%)	1.15%
handshake_tickets_ring_1.3_ecdsa_aes	7.64 ms	7.64 ms	0.00 ms (0.05%)	1.00%
handshake_session_id_ring_1.3_ecdsa_chacha	7.61 ms	7.61 ms	-0.00 ms (-0.04%)	1.00%
handshake_session_id_ring_1.3_rsa_chacha	7.48 ms	7.48 ms	0.00 ms (0.02%)	1.00%
handshake_tickets_ring_1.3_rsa_aes	7.53 ms	7.52 ms	-0.00 ms (-0.02%)	1.00%
handshake_no_resume_aws_lc_rs_1.2_rsa_aes	1.35 ms	1.35 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 (890c8ba)
• Candidate repo: https://github.com/cpu/rustls.git
• Candidate branch: cpu-consistent-example-docs (cef086d)

[djc]

Tiny nit: I would probably prefer having an empty line between the module-level docstring and the first line of code.

[cpu]

I would probably prefer having an empty line between the module-level docstring and the first line of code.

Fixed and rebased on main.