Merge branch 'develop' into topic/RDKEMW-9595_Analytics_addtionalContext

Author: Adrian Muzyka

.github/copilot-instructions.md

@@ -5,9 +5,9 @@ When writing review comments, include a direct GitHub link to the specific viola
 
       Correct Example:
       
-      https://github.com/rdkcentral/entservices-apis/blob/develop/.github/instructions/api_headers.instructions.md#enum-naming
+      https://github.com/rdkcentral/entservices-apis/blob/develop/.github/instructions/api_headers.instructions.md#json-rpc-tagging
 
-      https://github.com/rdkcentral/entservices-apis/blob/develop/.github/instructions/tags.instructions.md#json-rpc-tagging
+      https://github.com/rdkcentral/entservices-apis/blob/develop/.github/instructions/api_headers_notifications.instructions.md#notification-name-formatting
 
       Incorrect Example:
       

.github/instructions/api_headers.instructions.md

@@ -1,116 +1,92 @@
 ---
 applyTo: "apis/**/I*.h"
 ---
-      
-# Interface Header Specification Instructions(apis/**/I*.h)
-This document details the guidelines for defining interface headers for RDK Entertainment Services APIs, to ensure consistency and compliance with Thunder Plugins Interface standards. These guidelines have to be taken into account for each review. All interface headers MUST adhere to below Thunder Plugins Interface Guidelines.
 
-
-## Notification Interfaces
+## JSON RPC Tagging
    ### Requirement:
-      - Notification interfaces MUST provide default (empty) implementations for notification methods;
-      - Do NOT use pure virtual methods.
-      - A single method can be defined in more than one line for code readability.
-   ### Example:
-      /* @event */
-      struct EXTERNAL INotification : virtual public Core::IUnknown {
-          // ...
-          virtual void OnFontColorChanged(const string& color) {}; // Default implementation
-          // ...
-      };
-   ### Incorrect Example:
-      /* @event */
-      struct EXTERNAL INotification : virtual public Core::IUnknown {
-          // ...
-          virtual void OnFontColorChanged(const string& color) = 0; // Pure virtual method
-          // ...
-      };
-
-##  Method Return Type
-    ### Requirement:
-       - All methods MUST return Core::hresult.
-       - Notification Methods need not return Core::hresult.
-    ### Example:
-       virtual Core::hresult BindDriver(const string& deviceName) const = 0;
-
-##  API & Event Naming for Interface and JSON RPC
-    ### PascalCase in Interface Header and COMRPC:
-       - Method & Event names SHOULD be in Pascal Case.
-    
-    ### Example
-       virtual Core::hresult **BindDriver**(const string& deviceName) const = 0;
-    
-       virtual void **OnDevicePluggedIn**(const USBDevice& device) {}
-
-    ### camelCase for JSON RPC (using @text annotation):
-       - API & Event names SHOULD be defined in camel case for json-rpc definition via Thunder Framework tags.
-    ### Example
-       **// @text bindDriver**
-      virtual Core::hresult BindDriver(const string& deviceName) const = 0;
-      **// @text onDevicePluggedIn**
-      virtual void OnDevicePluggedIn(const USBDevice& device) {};
+      If an interface implements JSON-RPC and includes the @json tag, then:
+         
+         The interface must specify it's version (e.g., @json 1.0.0).
 
-## Enum Naming
-   ### Requirement:
-      - Enum names SHOULD be ALL_UPPER_SNAKE_CASE.
-      - Enum names SHOULD NOT contain any special characters other than underscore.
-        
-   ### Example:
-      enum USBStorageMountFlags : uint8_t {
-          READ_ONLY  = 1,  // READ ONLY
-          READ_WRITE = 2   // READ WRITE
-      };
-      #### Exception:
-            Standardized names (e.g., kHz) MAY be exempt.
+         The interface must also include the @text:keep tag.
 
-## Getter/Setter Naming
-   ### Requirement:
-      - API getters SHALL always start with get and Setters SHALL always start with set.
-      - All the getter and setter method names should be in PascalCase.
-      - All the getter and setter method names should be in camelCase when defining via @text annotations/tags.
    ### Example:
-         // @text getDefaultInterface
-         virtual Core::hresult GetDefaultInterface(/* ... */) const = 0; 
-         // @text setDefaultInterface
-         virtual Core::hresult SetDefaultInterface(/* ... */) = 0;
-
-## Event Naming Convention
-    ### Format:
-       - Event names SHOULD follow on[Object][Action].
-       - Event names not starting with on and not following this naming convention order should be flagged as errors during code review.
-          - Object: Noun giving context.
-          - Action: Verb (present/past tense for timing).
-    ### Interface Header Example (PascalCase):
-            struct EXTERNAL INotification : virtual public Core::IUnknown {
-            // ...
-            virtual void **OnAppResumed**() {}
-            // ...
-            }
-           struct EXTERNAL INotification : virtual public Core::IUnknown {
-             // ...
-             virtual void **OnAppResuming**() {}
-             //...
-           }
-
-   ### JSON RPC Example (camelCase via annotation):
-         struct EXTERNAL INotification : virtual public Core::IUnknown {
-            // ...
-            // @text **onAppResumed**
-            virtual void OnAppResumed() {};
-            // ...
-         }
-
-         struct EXTERNAL INotification : virtual public Core::IUnknown {
-             // ...
-            // @text **onAppResuming**
-             virtual void OnAppResuming() {};
-            // ...
-         }
-
+            /* @json 1.0.0 @text:keep */
+            struct EXTERNAL ITextTrack : virtual public Core::IUnknown {
+                // ...
+            };
+			
 ## Acronym Capitalization
     ### Requirement:
        - Acronyms SHOULD be fully capitalized.
 
     ### Example:
        virtual Core::hresult SetHDMIEnabled(bool enabled) = 0;
        // NOT: SetHdmiEnabled
+	   
+	   
+## Documentation Tags Guidelines
+      To ensure consistency and clarity in interface documentation, each method, event, and struct member must be annotated using the following tags. If any methods/events/struct members have not been annotated with the tags below, then they should be flagged as an error during PR review.
+    
+       ### Required Tags:
+    
+        - @brief — A concise description of the purpose or behavior.
+        - @param — Description of each parameter, including its name and purpose.
+        - @retval <ErrorCode>: <Description> — Used to describe each return code associated with a function or property. These descriptions will be included in the generated markdown documentation.
+        - @details (optional) — Additional information or extended explanation.
+
+      ### Method Example:
+            // @text onApplicationStateChanged
+            // @brief Triggered when the cast service receives an application state change notification from a client
+            // @param applicationName: Registered application name
+            // @param state: Application state
+            // @param applicationId: Application instance ID
+            // @param error: Error string, if any
+            // @retval ErrorCode::NONE: Indicates successful state change
+            // @retval ErrorCode::FORBIDDEN: Operation is not permitted
+            // @retval ErrorCode::UNAVAILABLE: Requested resource is not available
+            // @retval ErrorCode::INVALID: Provided state is not recognized
+            // @retval ErrorCode::INTERNAL: Internal server error occurred
+            virtual Core::hresult ApplicationStateChanged(
+                const string& applicationName /* @text applicationName */,
+                const State& state /* @text state */,
+                const string& applicationId /* @text applicationId */,
+                const ErrorCode& error /* @text error */
+            ) = 0;
+
+     ### Event Example:
+             struct EXTERNAL INotification : virtual public Core::IUnknown {
+             // @text onApplicationLaunchRequest
+             // @brief Triggered when the cast service receives a launch request from a client with launch params
+             // @param applicationName: Registered application name
+             // @param strPayLoad: Payload string to be passed to the application
+             // @param strQuery: Query string to be appended in launch request
+             // @param strAddDataUrl: Additional data URL to be passed to the application
+             virtual void OnApplicationLaunchRequestWithLaunchParam(
+                 const string& appName /* @text applicationName */,
+                 const string& strPayLoad /* @text strPayLoad */,
+                 const string& strQuery /* @text strQuery */,
+                 const string& strAddDataUrl /* @text strAddDataUrl */
+             ) {}
+         };
+
+      ### Struct Member Example:
+              struct EXTERNAL ApplicationInfo {
+                   string appName /* @text names */ 
+                                /* @brief Group of acceptable names for a related application. Application name in request URI must have exact match to one of the names. Otherwise, matching prefix is needed. If the application name in request URI does not match any names or prefixes, then the request shall fail */;
+                   
+                   string prefixes /* @text prefixes */ 
+                                   /* @brief If the application name in request URI does not match the list of names, it must contain one of the prefixes. If the application name in request URI does not match any names or prefixes, then the request shall fail */;
+                   
+                   string cors /* @text cors */ 
+                               /* @brief A set of origins allowed for the application. This must not be empty */;
+                   
+                   string query /* @text query */ 
+                                /* @brief Query string that needs to be appended in launch request */;
+                   
+                   string payload /* @text payload */ 
+                                  /* @brief Optional payload string that needs to be appended in launch request */;
+                   
+                   int allowStop /* @text allowStop */ 
+                                 /* @brief Indicates whether the application (matching name list or prefix list) is allowed to stop (no PID presence) after launch */;
+               };