Update doc generation logic from header

README.md

@@ -59,34 +59,23 @@ TO BE UPDATED!!
 
 - By default, the APIs are defined / described using header file so COMRPC is inherently supported by default (Refer entservices-apis/apis/<service name>/<servicename>.h for example)
 
-- When the implementation of a given Ent Service is expected to support JSONRPC in addition to COMRPC, then the tool available under tools/json_generator/generate_json.py SHALL be used to generate the required JSON Schema files from the headerfile defined for COMRPC.
+- API documentation is generated directly from the API header files themselves. This ensures a single-source-of-truth, as opposed to creating a JSON for documentation. Using JSON to generate documentation has been deprecated. 
 
-- When the implementation of a given Ent Service is expected to support only JSONRPC, the APIs are described using [JSON Schema](https://json-schema.org/). In this case, the required JSON schema files SHALL be created manually as per the details provided below.
+- To generate documentation, the header files should have doxygen comments and descriptions as specified in this [README](./tools/md_from_h_generator/README.md). The README also contains information on running the tool locally. The IFrameRate.h and IUSBMassStorage.h plugin header files are examples of supported Doxygen tagging.
 
-  - JSON Schema provides a standard approach for describing APIs and ensures consistency across all APIs. There are two schemas that are used to describe a service:
-
-  - * [plugin.schema.json](https://github.com/rdkcentral/entservices-apis/blob/main/tools/md_generator/json2md/schemas/plugin.schema.json): A schema for defining a service.
-  - * [interface.schema.json](https://github.com/rdkcentral/entservices-apis/blob/main/tools/md_generator/json2md/schemas/interface.schema.json): A schema for defining the properties, methods, and events of a service.
-
-Markdown files are generated from the header file / JSON definitions using the md_generator tool (`tools/md_generator/generate_md.py`).
+- Markdown files are generated from the header file definitions using the md_from_h_generator tool (tools/md_from_h_generator/generate_md_from_header.py).
 
+- The tool
 The generator tool requires:
 
-* Python 3.5 or higher
-* The jsonref library
+* Python 3.8.10 or higher
 
 Verify your Python version:
 
 ```shell
 python --version
 ```
 
-Install jsonref if it is not already installed:
-
-```shell
-pip install jsonref
-```
-
 ### Generating Markdown for a Single Service ###
 
 To generate markdown for a single service:

apis/FrameRate/IFrameRate.h

@@ -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 };
@@ -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 framerateMode: 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

apis/USBMassStorage/IUSBMassStorage.h

@@ -26,6 +26,7 @@
 namespace WPEFramework {
 namespace Exchange {
 /* @json 1.0.0 @text:keep */
+// @plugindescription The `USBMassStorage` plugin is using For mounting the file system on mass storage and enumeration of mount points.
 struct EXTERNAL IUSBMassStorage : virtual public Core::IUnknown
 {
     enum { ID = ID_USB_MASS_STORAGE };
@@ -47,32 +48,32 @@ struct EXTERNAL IUSBMassStorage : virtual public Core::IUnknown
 
     struct USBStorageDeviceInfo
     {
-        string   devicePath     /* @brief Device path in the file system (sysfs) */;
-        string   deviceName     /* @brief Device name identifying the device */;
+        string   devicePath     /* @brief Device path in the file system (sysfs) e.g. "/dev/sda" */;
+        string   deviceName     /* @brief Device name identifying the device e.g. "001/006"*/;
     };
 
     using IUSBStorageDeviceInfoIterator = RPC::IIteratorType<USBStorageDeviceInfo, ID_USB_MASS_STORAGE_DEVICE_INFO_ITERATOR>;
 
     struct USBStorageMountInfo
     {
-        string                  partitionName  /* @brief name of the partition */;
-        USBStorageMountFlags    mountFlags     /* @brief Mount flags used for mounting the device / partition */;
-        string                  mountPath      /* @brief path at which the partition is mounted on */;
+        string                  partitionName  /* @brief name of the partition e.g. "/dev/sda1" */;
+        USBStorageMountFlags    mountFlags     /* @brief Mount flags used for mounting the device / partition e.g. "READ_ONLY"*/;
+        string                  mountPath      /* @brief path at which the partition is mounted on e.g. "/tmp/media/usb2" */;
         USBStorageFileSystem    fileSystem     /* @brief file system of the partition */;
     };
 
     using IUSBStorageMountInfoIterator = RPC::IIteratorType<USBStorageMountInfo, ID_USB_MASS_STORAGE_MOUNT_INFO_ITERATOR>;
 
     struct USBStoragePartitionInfo
     {
-        USBStorageFileSystem    fileSystem      /* file system of the partition */;
-        uint32_t                size            /* total size of the partition in MB */;
-        uint64_t                startSector     /* start sector of the partition */;
-        uint64_t                numSectors      /* number of sectors in the partition */;
-        uint32_t                sectorSize      /* size of the sector in the partition in bytes */;
-        uint32_t                totalSpace      /* total space of the partition in MB */;
-        uint32_t                usedSpace       /* used space in the partition in MB */;
-        uint32_t                availableSpace /* available space in the partition in MB */;
+        USBStorageFileSystem    fileSystem;      // file system of the partition e.g. "VFAT"
+        uint32_t                size            /* total size of the partition in MB e.g. "1024" */;
+        uint64_t                startSector     /* start sector of the partition e.g. "2048" */;
+        uint64_t                numSectors      /* number of sectors in the partition e.g. "4096" */;
+        uint32_t                sectorSize      /* size of the sector in the partition in bytes e.g. "512" */;
+        uint32_t                totalSpace      /* total space of the partition in MB e.g. "1024" */;
+        uint32_t                usedSpace       /* used space in the partition in MB e.g. "512" */;
+        uint32_t                availableSpace /* available space in the partition in MB e.g. "512" */;
     };
 
 

batch_bash.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+
+# filepath: /path/to/script.sh
+
+# Directory containing the input files
+INPUT_DIR="apis"
+
+# Path to your Python script
+PYTHON_SCRIPT="./tools/md_from_h_generator/generate_md_from_header.py"
+
+# Loop through all files in the input directory
+for FOLDER in "$INPUT_DIR"/*; do
+    for FILE in "$FOLDER"/*.h; do
+        if [ -f "$FILE" ]; then
+            python3 "$PYTHON_SCRIPT" "$FILE"
+            echo "Processed $FILE"
+        fi
+    done
+done