Skip to content

Update doc generation logic from header #343

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 6 commits into from
Closed

Update doc generation logic from header #343

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
270ce1c
Fix the documentation generation logic from header
arun-madhavan-013 Jul 1, 2025
a3a5d88
Add variable name override support for @in and @out with @text
arun-madhavan-013 Jul 1, 2025
f3c416c
Fix the event and method example template mixup
arun-madhavan-013 Jul 1, 2025
378d4ae
Make the ID value unique
arun-madhavan-013 Jul 1, 2025
67e011c
Logic to handle @see, to add proper description for @text overrides a…
arun-madhavan-013 Jul 2, 2025
c313d53
Update the ReadMe.md with @plugindescription usage
arun-madhavan-013 Jul 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 52 additions & 36 deletions apis/FrameRate/IFrameRate.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ namespace WPEFramework
namespace Exchange
{
/* @json 1.0.0 @text:keep */
// @plugindescription This plugin allows to collect FPS related data on TV profile stack.
struct EXTERNAL IFrameRate : virtual public Core::IUnknown
{
enum { ID = ID_FRAMERATE };
Expand All @@ -37,79 +38,94 @@ namespace WPEFramework
enum { ID = ID_FRAMERATE_NOTIFICATION };

// @text onFpsEvent
// @brief Triggered by callback from FrameRate after onFpsEvent
// @param average - in - int
// @param min - in - int
// @param max - in - int
virtual void OnFpsEvent(const int average, const int min, const int max) {};
// @details Triggered at the end of each interval as defined by the `setCollectionFrequency` method
// after `startFpsCollection` method and once after the `stopFpsCollection` method is invoked
// @param average: The average FPS e.g. 60
// @param min: The minimum FPS e.g. 30
// @param max: The maximum FPS e.g. 120
virtual void OnFpsEvent(const int average /* @in */, const int min /* @in */, const int max /* @in */) {};

// @text onDisplayFrameRateChanging
// @brief Triggered when the framerate changes started
// @param displayFrameRate - in - string
virtual void OnDisplayFrameRateChanging(const string& displayFrameRate) {};
// @details This event is triggered when the display frame rate is about to change
// and represented as "WIDTHxHEIGHTxFPS".
// @param displayFrameRate: The new display frame rate e.g. "1920x1080x60"
virtual void OnDisplayFrameRateChanging(const string& displayFrameRate /* @in */) {};

// @text onDisplayFrameRateChanged
// @brief Triggered when the framerate changed.
// @param displayFrameRate - in - string
virtual void OnDisplayFrameRateChanged(const string& displayFrameRate) {};
// @details This event is triggered after the display frame rate has changed
// and represented as "WIDTHxHEIGHTxFPS".
// @param displayFrameRate: The new display frame rate e.g. "1920x1080x60"
virtual void OnDisplayFrameRateChanged(const string& displayFrameRate /* @in */) {};
};

// @omit
virtual Core::hresult Register(IFrameRate::INotification* notification) = 0;
// @omit
virtual Core::hresult Unregister(IFrameRate::INotification* notification) = 0;

/** Gets the Display Frame Rate*/
// @text getDisplayFrameRate
// @brief Gets the current display frame rate values.
// @param framerate - out - string
// @param success - out - boolean
// @details Retrieves the current display frame rate as a string in the format "WIDTHxHEIGHTpxFPS"
// @param framerate: The current display frame rate. e.g. "3840x2160px60"
// @param success: Indicates if the operation was successful e.g. True
// @returns Core::hresult
virtual Core::hresult GetDisplayFrameRate(string& framerate /* @out */, bool& success /* @out */) = 0;

/** Gets framerate mode */
// @text getFrmMode
// @brief Gets the current auto framerate mode.
// @param frmmode - out - int
// @param success - out - boolean
// @details Retrieves the current auto framerate mode as an integer. Expeted values are 0 or 1.
// @param auto-frm-mode: The current auto framerate mode. e.g. 1
// @param success: Indicates if the operation was successful. e.g. True
// @returns Core::hresult
virtual Core::hresult GetFrmMode(int &framerateMode /* @out @text:auto-frm-mode */, bool& success /* @out */) = 0;

/** Sets the FPS data collection interval */
// @text setCollectionFrequency
// @brief Sets the FPS data collection interval.
// @param frequency - in - int
// @param success - out - boolean
virtual Core::hresult SetCollectionFrequency(const int frequency, bool& success /* @out */) = 0;
// @details Sets the interval for FPS data collection in milliseconds. Default is 10000ms and min is 100ms
// @param frequency: The collection frequency in ms. e.g. 1000
// @param success: Indicates if the operation was successful. e.g. True
// @returns Core::hresult
virtual Core::hresult SetCollectionFrequency(const int frequency /* @in */, bool& success /* @out */) = 0;

/** Sets the display framerate values */
// @text setDisplayFrameRate
// @brief Sets the display framerate values.
// @param framerate - in - string
// @param success - out - boolean
virtual Core::hresult SetDisplayFrameRate(const string& framerate, bool& success /* @out */) = 0;
// @details Sets the display framerate to the specified value in the format "WIDTHxHEIGHTpxFPS".
// @param framerate: The display framerate to set. e.g. "3840px2160px30"
// @param success: Indicates if the operation was successful. e.g. True
// @returns Core::hresult
virtual Core::hresult SetDisplayFrameRate(const string& framerate /* @in */, bool& success /* @out */) = 0;

/** Sets the auto framerate mode */
// @text setFrmMode
// @brief Set the Frm mode.
// @param frmmode - in - int
// @param success - out - boolean
// @details Sets the auto framerate mode to the specified value. Expected values are 0(disable) or 1(enable).
// @param frmmode: The framerate mode to set. e.g. 1
// @param success: Indicates if the operation was successful. e.g. True
// @returns Core::hresult
virtual Core::hresult SetFrmMode(const int frmmode /* @in */, bool& success /* @out */) = 0;

/** Starts the FPS data collection */
// @text startFpsCollection
// @brief Starts the FPS data collection. Starts the FPS data collection
// @param success - out - boolean
// @details Starts collecting FPS data at the configured interval set by the method `SetCollectionFrequency`.
// @see onFpsEvent
// @param success: Indicates if the operation was successful. e.g. True
// @returns Core::hresult
virtual Core::hresult StartFpsCollection(bool& success /* @out */) = 0;

/** Stops the FPS data collection */
// @text stopFpsCollection
// @brief Stops the FPS data collection
// @param success - out - boolean
// @details Stops the FPS data collection.
// @param success: Indicates if the operation was successful. e.g. True
// @returns Core::hresult
virtual Core::hresult StopFpsCollection(bool& success /* @out */) = 0;

/** Update the FPS value */
// @text updateFps
// @brief Update the FPS value
// @param newFpsValue - in - int
// @param success - out - boolean
virtual Core::hresult UpdateFps(const int newFpsValue, bool& success /* @out */) = 0;
// @details Updates the current FPS value to the specified value represented as integer.
// @see onFpsEvent
// @param newFpsValue: The new FPS value. e.g. 60
// @param success: Indicates if the operation was successful. e.g. True
// @returns Core::hresult
virtual Core::hresult UpdateFps(const int newFpsValue /* @in */, bool& success /* @out */) = 0;
};
} // namespace Exchange
} // namespace WPEFramework
46 changes: 37 additions & 9 deletions tools/md_from_h_generator/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ virtual uint32_t initialize();
- **Required**: Yes (Mandatory tag for all methods/properties/events)
- **Usage**:
- Use this tag for a short, one-line description of the method.
- The description following this tag will be shown on the method/property/event table of contents
- The description following this tag will be shown on the method/property/event table of contents

### Example:

Expand Down Expand Up @@ -98,7 +98,7 @@ virtual uint32_t initialize();
- **Required**: No (Optional tag)
- **Usage**:
- Use this tag to reference related methods, classes, or external documentation.
- The linked event name should appear exactly as it is declared, without parenthesis
- The linked event name should appear exactly as it is declared, without parenthesis
- This tag is optional, but should be used if a corresponding event is defined in INotifications

### Example:
Expand Down Expand Up @@ -140,28 +140,29 @@ virtual void onInitialize();
- Parameter/symbol examples should be defined here (see [Providing Symbol Examples](#providing_examples))
- Specify the parameter name and its description. Format can include colon i.e. `@param [param_name]: [description]` or `@param [para_name] [description]`
- IMPORTANTLY, in addition to using the param tag, mark each parameter with inline 'in/out' information in the parameter list. If a parameter does not have inline in/out information, it defaults to 'in'.
- Additionally a parameter name override can be specified by combining `@in` or `@out` followed by `@text:varible-override-name` in the function declaration.

### Example:

***Header File Example:***
```cpp
/**
/**
...
* @param configPath: The config file path for initialization e.g. "../build/test.conf"
* @param status The status of the initialization. Set to true if completed.
*/
virtual uint32_t initialize(const string& configPath /* @in */, bool status /* @out */);
virtual uint32_t initialize(const string& configPath /* @in @text:config-path */, bool status /* @out @text:status-response */);
```

***Generated Markdown Example:***
> ### Parameters
> | Name | Type | Description |
> | :-------- | :-------- | :-------- |
> | config | string | The config file path for initialization |
> | config-path | string | The config file path for initialization |
> ### Results
> | Name | Type | Description |
> | :-------- | :-------- | :-------- |
> | status | bool | The status of the initialization. Set to true if completed. |
> | status-response | bool | The status of the initialization. Set to true if completed. |

---

Expand Down Expand Up @@ -209,21 +210,48 @@ virtual uint32_t internalMethod();

**Example**:
```cpp
/*
/*
* @property
* @brief Video output port on the STB used for connection to TV
* @param name: video output port name
*/
virtual uint32_t PortName (string& name /* @out */) const = 0;
```

### 9. `@plugindescription`
- **Purpose**: Provides option to override the generic plugin description text
- **Required**: No (Mandatory tag if method is a property)
- **Usage**:
- Use this tag for overriding the generic plugin description.

**Example**:
```cpp
namespace Exchange
{
/* @json 1.0.0 @text:keep */
// @plugindescription This plugin provides so and so functionalities
struct EXTERNAL IClassName : virtual public Core::IUnknown
{
```

***Generated Markdown Example:***

> <a id="head.Description"></a>
> # Description
>
> This plugin provides so and so functionalities
>
> The plugin is designed to be loaded and executed within the Thunder framework. For more information about the framework refer > > to [[Thunder](#ref.Thunder)].
>
> <a id="head.Configuration"></a>

---

## 4. Additional Features and Guidelines

<a id="providing_examples"></a>

### Providing Symbol Examples
### Providing Symbol Examples
In the RDK Services and Entservices APIs, plugins communicate using RPC. To facilitate this, the documentation includes relevant examples of request and response JSON structures. The md_from_h tool automates the creation of these examples by parsing enums, structs, iterators, and basic types declared in the header file, as well as extracting examples from @param Doxygen tags.

The tool maintains a global symbol registry to track the names and types of parameters declared in methods, properties, events, enums, and struct members. The goal of the global symbol registry is to make it easier and more consistent to provide examples for symbols which appear multiple times in a header file (such as preferredLanguages in IUserSettings.h). Examples are generated by analyzing the @param tags, where the tool uses a regular expression to extract text following the pattern `e.g. "(.*)"` in the parameter description. The value inside the quotes is then used as the example for that symbol. The pattern `ex: (.*)` is also matched in cases where examples have double-quotes. Additionally, examples can be derived from structs if their members include descriptive comments.
Expand Down Expand Up @@ -258,7 +286,7 @@ The following demonstrates how examples are set for struct members:

***Header File Example:***
```cpp
struct USBDevice {
struct USBDevice {
uint8_t deviceClass /* @brief USB class of the device as per USB specification e.g. "10" */ ;
uint8_t deviceSubclass /* @brief USB sub class of the device as per USB specification e.g. "6" */;
string deviceName /* @brief Name of the USB device e.g. "001/003"*/;
Expand Down
29 changes: 15 additions & 14 deletions tools/md_from_h_generator/generate_md_from_header.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,34 +35,35 @@ def generate_md_from_header(header_file):
filename = os.path.basename(header_file)
classname, _ = os.path.splitext(filename)

# Remove the leading 'I' from the api's class name
output_file_path = './tools/md_from_h_generator/generated_docs/' + classname[1:] + 'Plugin.md'

log_file_path = './tools/md_from_h_generator/logs/' + classname + '.txt'
logger = Logger(log_file_path)

header_structure = HeaderFileParser(header_file, logger)
header_structure.build_all_canonical_dicts()

# Remove the leading 'I' from the api's class name
output_file_path = './tools/md_from_h_generator/generated_docs/' + header_structure.classname + 'Plugin.md'

with open(output_file_path, 'w', encoding='utf-8') as file:
file.write(generate_header_toc(classname, header_structure))
file.write(generate_header_description_markdown(classname))
file.write(generate_header_toc(header_structure.classname, header_structure))
file.write(generate_header_description_markdown(header_structure.classname, getattr(header_structure, 'plugindescription', '')))
if len(header_structure.methods.values()) > 0:
file.write(generate_methods_toc(header_structure.methods, classname))
for method_name, method_info in header_structure.methods.items():
file.write(generate_methods_toc(header_structure.methods, header_structure.classname))
for idx, (method_name, method_info) in enumerate(header_structure.methods.items(), start=1):
file.write(generate_method_markdown(
method_name, method_info, header_structure.symbols_registry))
method_name, method_info, header_structure.symbols_registry, header_structure.classname, idx, header_structure.events))
file.write("\n")
if len(header_structure.properties.values()) > 0:
file.write(generate_properties_toc(header_structure.properties, classname))
for prop_name, prop_info in header_structure.properties.items():
file.write(generate_properties_toc(header_structure.properties, header_structure.classname))
for idx, (prop_name, prop_info) in enumerate(header_structure.properties.items(), start=1):
file.write(generate_property_markdown(
prop_name,prop_info, header_structure.symbols_registry))
prop_name, prop_info, header_structure.symbols_registry, header_structure.classname))
file.write("\n")
if len(header_structure.events.values()) > 0:
file.write(generate_notifications_toc(header_structure.events, classname))
for event_name, event_info in header_structure.events.items():
file.write(generate_notifications_toc(header_structure.events, header_structure.classname))
for idx, (event_name, event_info) in enumerate(header_structure.events.items(), start=1):
file.write(generate_notification_markdown(
event_name, event_info, header_structure.symbols_registry))
event_name, event_info, header_structure.symbols_registry, header_structure.classname, idx))
logger.write_log()
logger.close()

Expand Down
Loading
Loading