Skip to content

Conversation

kp-samuel-tam
Copy link
Member

Description

This PR adds comprehensive manual page generation and improves help documentation for lightway tools. The changes include:

  • Added new lightway-man package, running the binary will generate the manual pages
  • Enhanced --help text with extensive documentation for both client and server
  • man lightway-server is longer than lightway-server --help, with separate command_for_manpage() function
  • Updated Earthfile to include this in build process, i.e. earthy +build-man

This paves the way for building open-source graded Debian packages.

Motivation and Context

Users needed comprehensive documentation for lightway tools beyond basic --config-file help output. Manual pages provide the standard Unix way to access detailed documentation, while maintaining concise help for quick reference. This establishes a proper documentation foundation for the project.

How Has This Been Tested?

  • Verified manual page generation produces properly formatted documentation
  • Confirmed both brief --help and comprehensive manual pages work correctly
  • Tested that all packages compile successfully with the new dependencies
  • Ensured license checks pass with the updated deny.toml configuration
  • Validated Earthfile changes integrate manual generation into the build process
  • earthy +build-man works

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

  • My change requires a change to the documentation.
  • I have updated the documentation accordingly.
  • The correct base branch is being used, if not main

Copy link

github-actions bot commented Jul 1, 2025

Code coverage summary for db4d3cb:

Filename                                                     Regions    Missed Regions     Cover   Functions  Missed Functions  Executed       Lines      Missed Lines     Cover    Branches   Missed Branches     Cover
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
lightway-app-utils/src/args/cipher.rs                              4                 4     0.00%           1                 1     0.00%           5                 5     0.00%           0                 0         -
lightway-app-utils/src/args/connection_type.rs                     4                 4     0.00%           1                 1     0.00%           5                 5     0.00%           0                 0         -
lightway-app-utils/src/args/duration.rs                            7                 7     0.00%           5                 5     0.00%          13                13     0.00%           0                 0         -
lightway-app-utils/src/args/ip_map.rs                             11                11     0.00%           3                 3     0.00%          15                15     0.00%           0                 0         -
lightway-app-utils/src/args/logging.rs                            14                14     0.00%           2                 2     0.00%          16                16     0.00%           0                 0         -
lightway-app-utils/src/codec_ticker.rs                            47                 7    85.11%          17                 4    76.47%         172                11    93.60%           0                 0         -
lightway-app-utils/src/connection_ticker.rs                       71                11    84.51%          28                 4    85.71%         279                11    96.06%           0                 0         -
lightway-app-utils/src/dplpmtud_timer.rs                          63                 7    88.89%          22                 4    81.82%         282                11    96.10%           0                 0         -
lightway-app-utils/src/event_stream.rs                             5                 0   100.00%           3                 0   100.00%          13                 0   100.00%           0                 0         -
lightway-app-utils/src/iouring.rs                                157               142     9.55%          23                17    26.09%         304               281     7.57%           0                 0         -
lightway-app-utils/src/metrics.rs                                  2                 2     0.00%           2                 2     0.00%           4                 4     0.00%           0                 0         -
lightway-app-utils/src/sockopt/ip_mtu_discover.rs                 23                23     0.00%           4                 4     0.00%          93                93     0.00%           0                 0         -
lightway-app-utils/src/sockopt/ip_pktinfo.rs                       4                 4     0.00%           1                 1     0.00%          31                31     0.00%           0                 0         -
lightway-app-utils/src/tun.rs                                     75                75     0.00%          22                22     0.00%          93                93     0.00%           0                 0         -
lightway-app-utils/src/utils.rs                                   13                13     0.00%           1                 1     0.00%          11                11     0.00%           0                 0         -
lightway-client/src/args.rs                                       29                29     0.00%          25                25     0.00%          32                32     0.00%           0                 0         -
lightway-client/src/io/inside/tun.rs                              36                36     0.00%           7                 7     0.00%          40                40     0.00%           0                 0         -
lightway-client/src/io/outside/tcp.rs                             48                48     0.00%          10                10     0.00%          45                45     0.00%           0                 0         -
lightway-client/src/io/outside/udp.rs                             66                66     0.00%          12                12     0.00%          65                65     0.00%           0                 0         -
lightway-client/src/keepalive.rs                                 275                38    86.18%          61                 8    86.89%         405                28    93.09%           0                 0         -
lightway-client/src/lib.rs                                       284               284     0.00%          30                30     0.00%         402               402     0.00%           0                 0         -
lightway-client/src/main.rs                                       52                52     0.00%           7                 7     0.00%         176               176     0.00%           0                 0         -
lightway-core/src/borrowed_bytesmut.rs                            86                 1    98.84%          24                 0   100.00%         196                 1    99.49%           0                 0         -
lightway-core/src/builder_predicates.rs                           20                10    50.00%           4                 2    50.00%          28                14    50.00%           0                 0         -
lightway-core/src/cipher.rs                                        8                 0   100.00%           3                 0   100.00%          13                 0   100.00%           0                 0         -
lightway-core/src/connection.rs                                  693               376    45.74%          56                21    62.50%         932               420    54.94%           0                 0         -
lightway-core/src/connection/builders.rs                          62                22    64.52%          21                 8    61.90%         268                60    77.61%           0                 0         -
lightway-core/src/connection/dplpmtud.rs                         761                90    88.17%          66                 1    98.48%         944                11    98.83%           0                 0         -
lightway-core/src/connection/fragment_map.rs                     132                11    91.67%          27                 0   100.00%         290                 7    97.59%           0                 0         -
lightway-core/src/connection/io_adapter.rs                       137                17    87.59%          36                 5    86.11%         313                23    92.65%           0                 0         -
lightway-core/src/connection/key_update.rs                        23                 7    69.57%           5                 0   100.00%          38                19    50.00%           0                 0         -
lightway-core/src/context.rs                                      90                25    72.22%          25                 7    72.00%         208                40    80.77%           0                 0         -
lightway-core/src/context/ip_pool.rs                               7                 3    57.14%           1                 0   100.00%           6                 0   100.00%           0                 0         -
lightway-core/src/context/server_auth.rs                          14                11    21.43%           4                 3    25.00%          24                20    16.67%           0                 0         -
lightway-core/src/encoding_request_states.rs                       2                 0   100.00%           1                 0   100.00%           3                 0   100.00%           0                 0         -
lightway-core/src/io.rs                                            3                 3     0.00%           3                 3     0.00%          10                10     0.00%           0                 0         -
lightway-core/src/lib.rs                                           9                 6    33.33%           4                 1    75.00%          18                 9    50.00%           0                 0         -
lightway-core/src/metrics.rs                                      15                15     0.00%          13                13     0.00%          29                29     0.00%           0                 0         -
lightway-core/src/packet.rs                                       27                 7    74.07%           4                 1    75.00%          30                 6    80.00%           0                 0         -
lightway-core/src/plugin.rs                                       66                 8    87.88%          23                 5    78.26%         160                 9    94.38%           0                 0         -
lightway-core/src/utils.rs                                       101                21    79.21%          22                 2    90.91%         184                17    90.76%           0                 0         -
lightway-core/src/version.rs                                      37                 0   100.00%          19                 0   100.00%          89                 0   100.00%           0                 0         -
lightway-core/src/wire.rs                                        156                27    82.69%          32                 0   100.00%         267                 6    97.75%           0                 0         -
lightway-core/src/wire/auth_failure.rs                             9                 1    88.89%           3                 0   100.00%          19                 0   100.00%           0                 0         -
lightway-core/src/wire/auth_request.rs                           147                12    91.84%          34                 0   100.00%         287                 0   100.00%           0                 0         -
lightway-core/src/wire/auth_success_with_config_ipv4.rs           69                 4    94.20%          13                 0   100.00%         145                 0   100.00%           0                 0         -
lightway-core/src/wire/data.rs                                    20                 1    95.00%           7                 0   100.00%          43                 0   100.00%           0                 0         -
lightway-core/src/wire/data_frag.rs                               41                 1    97.56%          17                 0   100.00%          92                 0   100.00%           0                 0         -
lightway-core/src/wire/encoding_request.rs                        24                 2    91.67%           6                 0   100.00%          46                 1    97.83%           0                 0         -
lightway-core/src/wire/encoding_response.rs                       24                 2    91.67%           6                 0   100.00%          46                 1    97.83%           0                 0         -
lightway-core/src/wire/ping.rs                                    22                 3    86.36%           7                 0   100.00%          68                 0   100.00%           0                 0         -
lightway-core/src/wire/pong.rs                                    15                 2    86.67%           5                 0   100.00%          34                 0   100.00%           0                 0         -
lightway-core/src/wire/server_config.rs                           20                 2    90.00%           5                 0   100.00%          44                 0   100.00%           0                 0         -
lightway-server/src/args.rs                                       27                27     0.00%          27                27     0.00%          27                27     0.00%           0                 0         -
lightway-server/src/auth.rs                                      104                36    65.38%          19                 5    73.68%         148                28    81.08%           0                 0         -
lightway-server/src/connection.rs                                 53                53     0.00%          24                24     0.00%         128               128     0.00%           0                 0         -
lightway-server/src/connection_manager.rs                        160               160     0.00%          40                40     0.00%         298               298     0.00%           0                 0         -
lightway-server/src/connection_manager/connection_map.rs          87                 9    89.66%          26                 2    92.31%         273                 9    96.70%           0                 0         -
lightway-server/src/io/inside/tun.rs                              25                25     0.00%           8                 8     0.00%          34                34     0.00%           0                 0         -
lightway-server/src/io/outside/tcp.rs                             83                83     0.00%          10                10     0.00%         108               108     0.00%           0                 0         -
lightway-server/src/io/outside/udp.rs                            145               145     0.00%          19                19     0.00%         267               267     0.00%           0                 0         -
lightway-server/src/io/outside/udp/cmsg.rs                        47                16    65.96%          14                 5    64.29%         237                56    76.37%           0                 0         -
lightway-server/src/ip_manager.rs                                 82                25    69.51%          19                 4    78.95%         254                28    88.98%           0                 0         -
lightway-server/src/ip_manager/ip_pool.rs                        101                 1    99.01%          32                 0   100.00%         303                 0   100.00%           0                 0         -
lightway-server/src/lib.rs                                       100               100     0.00%          12                12     0.00%         162               162     0.00%           0                 0         -
lightway-server/src/main.rs                                       81                81     0.00%          10                10     0.00%         215               215     0.00%           0                 0         -
lightway-server/src/metrics.rs                                    93                91     2.15%          82                80     2.44%         220               216     1.82%           0                 0         -
lightway-server/src/statistics.rs                                 53                23    56.60%           8                 4    50.00%         103                42    59.22%           0                 0         -
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
TOTAL                                                           5371              2442    54.53%        1133               492    56.58%       10152              3709    63.47%           0                 0         -

✅ Region coverage 54% passes
✅ Line coverage 63% passes

@kp-samuel-tam kp-samuel-tam marked this pull request as ready for review July 1, 2025 04:24
@kp-samuel-tam kp-samuel-tam requested a review from a team as a code owner July 1, 2025 04:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants