RDKDEV-1102: Update documentation for Network plugin to align with NetworkManger documentation (#5928)#6465
Conversation
…tworkManger documentation (#5928) Reason for change: Align Network plugin documention with NetworkManager documention update Risks: Low Test Procedure: Verify default packet sizes for ping and trace APIs in https://rdkcentral.github.io/rdkservices/#/api/NetworkPlugin is aligned with https://github.com/rdkcentral/networkmanager/blob/develop/docs/NetworkManagerPlugin.md Signed-off-by: Jitha James <jitha_james@comcast.com> Co-authored-by: Karunakaran A <48997923+karuna2git@users.noreply.github.com> (picked from ce1f603)
There was a problem hiding this comment.
Pull request overview
Updates generated API documentation to mark legacy Network/Wifi Thunder plugins as deprecated and align ping/trace defaults with NetworkManager’s documentation.
Changes:
- Mark
NetworkPluginandWifiPlugindocs as deprecated and add a reference to NetworkManager documentation. - Update documented default
params.packetsvalues fororg.rdk.Network.ping(3) andorg.rdk.Network.trace(5), including request examples.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 10 comments.
| File | Description |
|---|---|
| docs/api/WifiPlugin.md | Adds deprecation marker and pointer to NetworkManager docs. |
| docs/api/NetworkPlugin.md | Adds deprecation marker and pointer to NetworkManager docs; updates ping/trace default packet counts and examples. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| <!-- Generated automatically, DO NOT EDIT! --> | ||
| <a name="Wifi_Plugin"></a> | ||
| # Wifi Plugin | ||
| # Wifi Plugin $${\color{red}(DEPRECATED)}$$ |
There was a problem hiding this comment.
The heading uses a KaTeX/LaTeX color expression ($${\color{red}...}$$) to mark deprecation. This is inconsistent with other generated API docs and may render as raw text depending on the markdown renderer used for the published site. Prefer a plain markdown deprecation marker (e.g., "(DEPRECATED)" or bold text) that will reliably render everywhere.
| # Wifi Plugin $${\color{red}(DEPRECATED)}$$ | |
| # Wifi Plugin (DEPRECATED) |
| | params | object | | | ||
| | params.endpoint | string | The host name or IP address | | ||
| | params.packets | integer | The number of packets to send. Default is 15 | | ||
| | params.packets | integer | The number of packets to send. Default is 3 | |
There was a problem hiding this comment.
The default packet count was updated here, but the related pingNamedEndpoint section later in this document still states a default of 15 packets. Please update the named-endpoint variant too (or clarify if the defaults intentionally differ) to keep the documentation consistent.
| | params.packets | integer | The number of packets to send. Default is 3 | | |
| | params.packets | integer | The number of packets to send for this `ping` call. Default is 3 | |
| | params | object | | | ||
| | params.endpoint | string | The host name or IP address | | ||
| | params.packets | integer | The number of packets to send. Default is 15 | | ||
| | params.packets | integer | The number of packets to send. Default is 5 | |
There was a problem hiding this comment.
The default packet count was updated here, but the related traceNamedEndpoint section later in this document still states a default of 15 packets. Please update the named-endpoint variant too (or clarify if the defaults intentionally differ) to keep the documentation consistent.
| | params.packets | integer | The number of packets to send. Default is 5 | | |
| | params.packets | integer | The number of packets to send. The default is 5 packets. | |
| | params | object | | | ||
| | params.endpoint | string | The host name or IP address | | ||
| | params.packets | integer | The number of packets to send. Default is 15 | | ||
| | params.packets | integer | The number of packets to send. Default is 3 | |
There was a problem hiding this comment.
PR description mentions verifying default packet sizes for ping/trace, but the changes here adjust the default number of packets (params.packets). Please update the PR description (or the doc wording) to avoid confusion.
| "params": { | ||
| "endpoint": "45.57.221.20", | ||
| "packets": 10, | ||
| "packets": 3, |
There was a problem hiding this comment.
The request example was updated to "packets": 3, but the response example immediately below still shows packetsTransmitted/packetsReceived as 10, making the example internally inconsistent. Please update the response example values to match the request packet count.
| <!-- Generated automatically, DO NOT EDIT! --> | ||
| <a name="Wifi_Plugin"></a> | ||
| # Wifi Plugin | ||
| # Wifi Plugin $${\color{red}(DEPRECATED)}$$ |
There was a problem hiding this comment.
This file is marked as auto-generated. To avoid the deprecation note being lost the next time docs are regenerated, consider setting info.deprecated and info.referencePluginUrl in the corresponding source JSON (e.g., WifiManager/WifiPlugin.json) and regenerating docs, rather than patching the generated markdown output.
|
|
||
| A org.rdk.Wifi plugin for Thunder framework. | ||
|
|
||
| For newer APIs, please refer: https://github.com/rdkcentral/networkmanager/blob/main/docs/NetworkManagerPlugin.md |
There was a problem hiding this comment.
This adds a bare URL. Please format it as a proper markdown link (and consider using the same deprecation wording/pattern used elsewhere in the generated docs) so it renders consistently in the documentation site.
| For newer APIs, please refer: https://github.com/rdkcentral/networkmanager/blob/main/docs/NetworkManagerPlugin.md | |
| For newer APIs, please refer to [NetworkManager Plugin](https://github.com/rdkcentral/networkmanager/blob/main/docs/NetworkManagerPlugin.md). |
| <!-- Generated automatically, DO NOT EDIT! --> | ||
| <a name="NetworkPlugin"></a> | ||
| # NetworkPlugin | ||
| # Network Plugin $${\color{red}(DEPRECATED)}$$ |
There was a problem hiding this comment.
The heading uses a KaTeX/LaTeX color expression ($${\color{red}...}$$) to mark deprecation. This is inconsistent with other generated API docs and may render as raw text depending on the markdown renderer used for the published site. Prefer a plain markdown deprecation marker (e.g., "(DEPRECATED)" or bold text) that will reliably render everywhere.
| # Network Plugin $${\color{red}(DEPRECATED)}$$ | |
| # Network Plugin (DEPRECATED) |
|
|
||
| A org.rdk.Network plugin for Thunder framework. | ||
|
|
||
| For newer APIs, please refer: https://github.com/rdkcentral/networkmanager/blob/main/docs/NetworkManagerPlugin.md |
There was a problem hiding this comment.
This adds a bare URL. Please format it as a proper markdown link so it renders consistently in the documentation site.
| For newer APIs, please refer: https://github.com/rdkcentral/networkmanager/blob/main/docs/NetworkManagerPlugin.md | |
| For newer APIs, please refer: [NetworkManager Plugin](https://github.com/rdkcentral/networkmanager/blob/main/docs/NetworkManagerPlugin.md) |
| <!-- Generated automatically, DO NOT EDIT! --> | ||
| <a name="NetworkPlugin"></a> | ||
| # NetworkPlugin | ||
| # Network Plugin $${\color{red}(DEPRECATED)}$$ |
There was a problem hiding this comment.
This file is marked as auto-generated. To avoid the deprecation note and defaults drifting from the source of truth, consider updating the corresponding source JSON (e.g., Network/NetworkPlugin.json / Network/Network.json) and regenerating docs rather than editing the generated markdown output directly.
Reason for change: Align Network plugin documentation with NetworkManager documentation update
Risks: Low
Test Procedure: Verify default packet sizes for ping and trace APIs in https://rdkcentral.github.io/rdkservices/#/api/NetworkPlugin is aligned with https://github.com/rdkcentral/networkmanager/blob/develop/docs/NetworkManagerPlugin.md
(picked from ce1f603)