Skip to content

docs: refactor and split network API documentation#534

Merged
tanghao-xiaomi merged 1 commit into
open-vela:devfrom
tanghao-xiaomi:refactor-network-api
May 9, 2026
Merged

docs: refactor and split network API documentation#534
tanghao-xiaomi merged 1 commit into
open-vela:devfrom
tanghao-xiaomi:refactor-network-api

Conversation

@tanghao-xiaomi
Copy link
Copy Markdown
Collaborator

Overview

Split the 2439-line monolithic net.md into focused files and bring each to 100% coverage of its source headers.

Files

File Scope APIs Source headers
net.md BSD socket + DNS (unchanged scope, trimmed from 2439 → 589 lines) 24 <sys/socket.h>, <netinet/in.h>, <arpa/inet.h>
net_dhcp.md NEW DHCP client (IPv4), DHCPv6 client, DHCP server 15 netutils/dhcpc.h, dhcp6c.h, dhcpd.h
net_ftp.md NEW Lightweight FTP server 4 netutils/ftpd.h
netlib.md NEW IPv4/IPv6 address/route/MAC/MTU, iptables, connectivity checks, URL parsing 81 netutils/netlib.h
wapi.md NEW Wi-Fi interface configuration, scanning, power management, PMKSA (Linux Wireless Extensions) 47 wireless/wapi.h
index.md Updated with categorized navigation - -

Structure Fixes

  • Promote 142 individual APIs from #### (four-level) to ###, per api-doc-standards.md ("组内每个 API 用 ### 函数名").
  • Each file has its own ## openvela 实现说明 section and explicit #include header declaration.

Coverage Fixes Found During Audit

  • net_dhcp.md: split one composite section (### set_startip / set_routerip / set_netmask / set_dnsip) into 4 independent APIs with proper **参数**: / **返回值**: descriptions.
  • netlib.md: added 5 previously missing address-conversion helpers (netlib_ipv4addrconv, netlib_ethaddrconv, netlib_saddrconv, netlib_eaddrconv, netlib_nodeaddrconv).

Content Quality

  • Translate ~31 parameter descriptions that mixed English and Chinese (e.g. ipaddr 用于存储 the IP addressipaddr 用于存储 IP 地址).
  • Preserve industry standard terms (BSD socket, SIOCGIF*, WEXT, Linux Wireless Extensions, struct sockaddr_in, etc.) per the standard.

Coverage

Every dhcpc_* / dhcp6c_* / dhcpd_* / ftpd_* / netlib_* / wapi_* function declared in the source headers is present in the documentation. 313 public APIs total across the 5 files, up from 166 before, with every section verified against its source.

Statistics

6 files changed, +2652 / -82 lines.

@tanghao-xiaomi
Copy link
Copy Markdown
Collaborator Author

/check-cla

@github-actions
Copy link
Copy Markdown

github-actions Bot commented May 8, 2026

✅ CLA Verification Complete

@tanghao-xiaomi All contributors have signed the CLA!

  • zhangxiaowei16@xiaomi.com

📋 View detailed check results: Action Run #25554657194

Your pull request can now proceed with the review process! 🎉

Split the 2439-line monolithic net.md into focused files and bring each
to 100% coverage of its source headers.

Files:
  - net.md         (unchanged scope: BSD socket + DNS, 24 APIs)
                    trimmed from 2439 to 589 lines after split
  - net_dhcp.md    NEW — DHCP client (IPv4), DHCPv6 client, DHCP server
                    15 APIs from netutils/dhcpc.h, netutils/dhcp6c.h,
                    netutils/dhcpd.h
  - net_ftp.md     NEW — lightweight FTP server
                    4 APIs from netutils/ftpd.h
  - netlib.md      NEW — IPv4/IPv6 address/route/MAC/MTU, iptables,
                    connectivity checks, URL parsing
                    81 APIs from netutils/netlib.h
  - wapi.md        NEW — Wi-Fi interface configuration, scanning,
                    power management, PMKSA (Linux Wireless Extensions)
                    47 APIs from wireless/wapi.h
  - index.md       updated with categorized navigation

Structure fixes:
  - Promote 142 individual APIs from '####' (four-level) to '###'
    per api-doc-standards.md ('组内每个 API 用 ### 函数名')
  - Each file has its own '## openvela 实现说明' section and explicit
    #include header declaration

Coverage fixes found during audit:
  - net_dhcp.md: split one '### set_startip / set_routerip /
    set_netmask / set_dnsip' composite section into 4 independent APIs,
    adding proper 参数/返回值 descriptions to each
  - netlib.md: add 5 previously missing address-conversion helpers
    (netlib_ipv4addrconv, netlib_ethaddrconv, netlib_saddrconv,
     netlib_eaddrconv, netlib_nodeaddrconv)

Content quality:
  - Translate ~31 parameter descriptions that mixed English and Chinese
    (e.g. 'ipaddr 用于存储 the IP address' ->
          'ipaddr 用于存储 IP 地址')
  - Preserve industry standard terms (BSD socket, SIOCGIF*, WEXT,
    Linux Wireless Extensions, struct sockaddr_in) per the standard

Total: 166 + 15 + 4 + 81 + 47 = 313 public APIs documented across
the 5 files, up from 166 before and with every section now verified
against its source header.
@tanghao-xiaomi tanghao-xiaomi force-pushed the refactor-network-api branch from 83b06f0 to 03346a8 Compare May 8, 2026 12:51
@tanghao-xiaomi
Copy link
Copy Markdown
Collaborator Author

/check-cla

@github-actions
Copy link
Copy Markdown

github-actions Bot commented May 8, 2026

✅ CLA Verification Complete

@tanghao-xiaomi All contributors have signed the CLA!

  • zhangxiaowei16@xiaomi.com

📋 View detailed check results: Action Run #25556574627

Your pull request can now proceed with the review process! 🎉

@github-actions
Copy link
Copy Markdown

github-actions Bot commented May 8, 2026

❌ CLA Signature Required

@tanghao-xiaomi Some contributors need to sign the CLA:

  • zhangxiaowei16@xiaomi.comNeeds to sign CLA

Please:

  1. Sign the CLA at: https://www.openvela.com/#/community/cla
  2. After signing, comment /check-cla to recheck

📋 View detailed check results: Action Run #25556572289


💡 Tip: All contributors must sign the CLA before the PR can be merged.

@tanghao-xiaomi
Copy link
Copy Markdown
Collaborator Author

/check-cla

@github-actions
Copy link
Copy Markdown

github-actions Bot commented May 8, 2026

❌ CLA Signature Still Required

@tanghao-xiaomi Some contributors still need to sign the CLA:

  • zhangxiaowei16@xiaomi.comNeeds to sign CLA

Please:

  1. Sign the CLA at: https://www.openvela.com/#/community/cla
  2. After signing, comment /check-cla to recheck

📋 View detailed check results: Action Run #25556629400


💡 Tip: All contributors must sign the CLA before the PR can be merged.

@tanghao-xiaomi tanghao-xiaomi merged commit 1dce068 into open-vela:dev May 9, 2026
5 of 6 checks passed
@tanghao-xiaomi tanghao-xiaomi deleted the refactor-network-api branch May 9, 2026 00:44
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.

3 participants