Tags

When designing a COM-RPC interface, it is possible to add specific comments (known as annotations or tags) that will drive the code generation.

All tags follow the same format of @ followed by the tag name. They can be inserted into the interface using either inline // comments or /* */ block comments. Tags can influence the generation of the COM-RPC ProxyStubs and the generated JSON-RPC interfaces. They can also be used to configure the documentation generation

Summary

General purpose tags

Tag	Short Description	Deprecated	StubGen	JsonGen	Scope
@stubgen:skip	Stop processing current file. Prefer `@omit`	Yes	Yes	Yes	File
@stop	Equivalent to `@stubgen:skip`. Prefer `@omit`.		Yes	Yes	File
@stubgen:omit	Omit processing of the next class or method		Yes	No (but has side-effects)	Class, Method
@omit	Same as `@stubgen:omit`		Yes	No (but has side-effects)	Class, Method
@stubgen:include	Insert another C++ file		Yes	Yes	File
@stubgen:stub	Emit empty function stub instead of full proxy implementation		Yes	No	Method
@stub	Same as `@stubgen:stub`		Yes	No	Method
@insert	Same as `@stubgen:include`		Yes	Yes	File
@define	Defines a literal as a known identifier		Yes	Yes	File

@stubgen:skip

Warning

This tag is deprecated. @omit is preferred over this tag.

The remaining portion of the file below this tag will be skipped from processing. If placed on top of the file, the complete file is skipped from processing.

Example

IDRM.h file is skipped from processing placing this tag at the top of this file.

@stop

Prefer @omit to this tag.

This tag is equivalent to @stubgen:skip but can be used as a last resort when the generator is technically unable to parse the file. However in such case it is recommended that the complicated part is moved to a separate header file instead.

@stubgen:omit

This tag is applied to structs, class or functions. When the struct/class marked as omit, proxy stubs will not be created for those. Includes inner classes/structs/enums. But @json tag will still be applicable to the struct/class.

Example

ITimeSync.h uses omit flag to skip the content of the whole file. This is the preferred way to skip the content.

@omit

Same as @stubgen:omit

@stubgen:include

This tag is used to include definitions from another file. This tag imports the contents of the file while creating json generation and as well as in stub generation.

Like #include preprocessor the contents of the files are included before processing any other tags. As with #include, it supports two formats:

"file" - include a C++ header file, relative to the directory of the current file
<file> - include a C++ header file, relative to the defined include directories
- Note: this is intended for resolving unknown types, classes defined in included headers are not considered for stub generation (except for template classes)

Example

IDeviceInfo.h includes com/IIteratorType.h to get the definition for RPC::IIteratorType

// @stubgen:include <com/IIteratorType.h>

@stubgen:stub

To avoid proxy implementation for a function, mark it with this tag.

Example

In IShell Submit function is marked as stub as it does not want that function to be called beyond Thunder process

@stub

Same as @stubgen:stub

@insert

Same as @stubgen:include

@define

Ddefines a literal as a known identifier (equivalent of #define in C++ code)

Example

// @define EXTERNAL

Tag	Short Description	StubGen	JsonGen	Scope
@in	Marks an input parameter	Yes	Yes	Method Parameter
@out	Marks an output parameter	Yes	Yes	Method Parameter
@inout	Marks as input and output parameter (equivalent to `@in @out`)	Yes	Yes	Method Parameter
@restrict	Specifies valid range for a parameter	Yes	Yes	Method Parameter
@interface	Specifies a parameter holding interface ID value for void* interface passing or indicates iterator should not be collated	Yes	No	Method paramter
@length	Specifies the expression to evaluate length of an array parameter (can be other parameter name, or constant, or math expression)	No	Yes	Method Parameter
@maxlength	Specifies a maximum buffer length value	No	Yes	Method parameter
@default	Provides a default value for an unset optional type	Yes	Yes	Method parameter

@in

This tag will mark a parameter in a function as an input parameter. By default, all parameters in a function are treated as input paramter.

All input paramters are expected to be const. If not, warning will be thrown during JSON-RPC code generation.

Example

In IDolby.h enable parameter is marked as an input parameter.

@out

This tag will mark a parameter in a function as an output parameter. By default, all parameters in a function are treated as input parameter.

Output parameters should either be a reference or a pointer and should not be constant. If these conditions are not met, Error will be thrown during JSON-RPC code generation.

Example

In IDolby.h supported parameter is marked as output paramter.

@inout

In few methods, a parameter will act both as input as well as output parameter. Such parameters are marked using this tag.

Example

In IDisplayInfo.h the parameter length acts both as input as well as the output.

While calling this API, application will fill the buffer size in the length paramenter. When the function returns, the parameter will have the modified length value. Thus acts as both input and output parameter

@restrict

Specifies a valid range for a parameter (e.g. it can indicate a valid size for buffers, strings, arrays, std::vector, or iterators). Ranges are inclusive.

If a parameter is outside the valid range, then there are two possibilities:

If running a debug build, an ASSERT will be triggered if the value is outside the allowed range
If the stub generator is invoked with the --secure flag, then the range will be checked on all builds and an error (ERROR_INVALID_RANGE) will be returned if the value is outside the range
If one just wants to indicate a string must contain at least one character, empty would not be valid, the tag @restrict:nonempty can be used with that parameter.

Example

@restrict:1..32 - Value must be between 1 and 32
@restrict:256..1K - Value must be between 256B and 1K in size
@restrict:1M - Value must be <= 1M in size

@interface

This tag specifies a parameter holding interface ID value for void* interface passing.

Functions like Acquire will return the pointer to the queried interface. For such functions, this tag will specify which field to look for to get the corresponding interface id.

A second usage for this tag is to indicate an iterator should not be collated. Iterators can be collated in Thunder (meaning all their values will be transferred in one go and all follow up Next calls will be local instead of remote). If this is not desired (e.g. because the iterator holds a huge number of items making this a too big of memory overhead or because you only need a few items from the iterator instead of most of them) one can add the interface with the iterator parameter or with the iterator typedef. At the moment the default behavior for the code generators is to have all iterators not collated. By passing the the flag --collated-iterators to the proxy stub generator all iterators will become collated, expect of the course the ones that have the tag @interface.

Example

In ICOM.h specifies parameter 3 interfaceId holds the interface id for the returned interface.

@length

This tag should be associated with an array. It specifies the expression to evaluate length of an array parameter (can be other parameter name, or constant, or math expression)

Use round parenthesis for expressions, e.g. @length:bufferSize @length:(width * height * 4)

Note @length:return can be used in case the length of the array is the return value of the method instead of an in/in-out parameter.

Example

From another parameter

/* @length:param1 */

From a constant.

/* @length:32 */

From an expression

/* @length:(param1+param2+16) */

In IOCDM.h:

function StoreLicenseData @length param is marked as constant.
function SelectKeyId @length tag is marked as another parameter.

returned

See here for an example.

@maxlength

Used with the @out or @inout tag. It specifies a maximum buffer length value (a constant, a parameter name or a math expression). If not specified, @length is considered as maximum length

When used with @inout it will use different buffer for output depending upon this tag. If not specified it will reuse the same input buffer for output as well.

Example

In IPerformance.h it specifies, the maximum length for the buffer.

@default

This tag should be associated with optional types. It provides a default value for JSON-RPC, even if no explicit value was set.

Note: Unless a parameter is optional, it must be set.

Note: Currently, OptionalType does not work with C-Style arrays, of course a fixed array of OptionalTypes is supported.

Example

In this example class, the OptionalType members have a default value that would be transmitted incase their values have not been set.

struct Store {
    enum sizetype: uint8_t {
        S, M, L
    };

    Core::OptionalType<string> Brand /* @default:"unknown" */;
    Core::OptionalType<sizetype> Size /* @default: M */;
};

virtual Core::hresult Shirt(const Core::OptionalType<Store>& London) = 0;

In IController.h it specifies, the default value assigned incase the parameter is not set.

Tag	Short Description	Deprecated	StubGen	JsonGen	Scope
@json	Marks a class as JsonGenerator input		No	Yes	Class
@json:omit	Marks a method/property/notification to omit		No	Yes	Method
@uncompliant:extended	Indicates the generated JSON-RPC code should use the old "extended" format for parameters	Yes	No	Yes	Class
@uncompliant:collapsed	Indicates the generated JSON-RPC code should use the old "collapsed" format for parameters	Yes	No	Yes	Class
@compliant	Indicates the generated JSON-RPC code should be strictly JSON-RPC compliant (default)		No	Yes	Class
@event	Marks a class as JSON notification		No	Yes	Class
@property	Marks a method as a property		No	Yes	Method
@iterator	Marks a class as an iterator		Yes	Yes	Class
@bitmask	Indicates that enumerator lists should be packed into into a bit mask	Yes	No	Yes	Method parameter
@index	Marks an index parameter to a property or notification		No	Yes	Method paramter
@opaque	Indicates that a string parameter is an opaque JSON object		No	Yes	Method parameter
@alt	Provides an alternative name a method can by called by		No	Yes	Method
@text	Renames identifier Method, Parameter, PoD Member, Enum, Interface		No	Yes	Enum, Method parameter, Method name, PoD member, Interface
@prefix	Prepends identifier for all JSON-RPC methods and properties in a class		No	Yes	Class
@statuslistener	Notifies when a JSON-RPC client registers/unregisters from an notification		No	Yes	Method
@async	Indicates a method is asynchronous for the JSON-RPC interface		No	Yes	Method
@encode	Encodes data into a different format		Yes	Yes	Method parameter
@wrapped	Encodes a single out parameter in a wrapped format		No	Yes	Class and Method parameter

@json

This tag helps to generate JSON-RPC files for the given Class/Struct/enum.

It will creates 3 files automatically:

JsonData_<structname>Output.h will have definitions for structs that are used in JsonMethods.
Jsonenum_<structname>Output.cpp will have definition for enums
J<InterfaceFilename>Output.h will have definition for the methods for JSON-RPC.

Example

IDisplayInfo.h uses this tag to generate JSON-RPC files.

It will create the following files:

Jsonenum_HDRProperties.cpp
JHDRProperties.h

@json:omit

This tag is used to leave out any Class/Struct/enum from generating JSON-RPC file.

Example

IBrowser.h uses this tag to remove HeaderList function from JSON-RPC file generation.

@uncompliant:extended

Warning

This tag is deprecated

When a JSON-RPC method is marked as a property (and therefore can only have a single parameter), allow providing that parameter value directly without enclosing it in a surrounding JSON object. For example:

params: "foobar"

This should not be used for new interfaces as does not comply strictly with the JSON-RPC specification.

@uncompliant:collapsed

Warning

This tag is deprecated

When any JSON-RPC method/property/notification only has a single parameter, allow that parameter value to be directly provided without enclosing it in a surrounding JSON object. For example:

params: "foobar"

This should not be used for new interfaces as does not comply strictly with the JSON-RPC specification.

@compliant

All JSON-RPC methods, notifications and properties should strictly comply to the JSON-RPC specification - meaning all parameters must be enclosed in a surrounding object with the name of the parameter and value:

params: { 
    "name":  "abcd"
}

This is the default behaviour so does not normally need adding to interfaces (unless the generator is being run with non-standard options)

@event

This tag is used in JSON-RPC file generation. This tag is used to mark a struct/class that will be called back as an notification by the framework.

Example

IDolby.h Whenever the audio mode changes AudioModeChanged API will be called.

@property

Mark a method to be a property when the intention is to perform simple get and set. It cannot have more than one parameter.

A method which does more than get and set should not be marked as property even if it is having a single parameter.
A property is said to be write only if its parameter is const and there no ther method definition with non const is given for reading.
A property is said to be read only if its parameter is non-const and there no ther method definition with const is given for setting.
A property is said to be both if it has both const and non-const version present.

Example

IDolby.h is a read only property as it does not have a const version for setting the property.
IBrowser.h is a write only property as it has only const version and not non const version is available.
IBrowser.h is a read write property as it has both const and non const version defined.

@iterator

This is a helper tag. This helps in generating helper functions to iterate through an array. The helper functions are defined in IIteratorType.h.

The interfaces which needs iteration functionality should include that header using @stubgen:include tag.

In Json Generator,it will help to convert the class to JsonArray.
In Proxy generation, it will help in generating the helper function like Current, Next, Previous for iterating through the array.

Example

IDeviceInfo.h uses @stubgen:include to insert the IIteratorType to that file.

Which in turn used to iterate through iterators in function AudioOutputs, VideoOutputs, Resolutions

@bitmask

Indicates that enumerator lists should be packed into into a bit mask.

Example

IBluetoothAudio.h uses @bitmask to indicate the supported audio codecs should be encoded as a bitmask.

@index

Used in conjunction with @property. Allows a property list to be accessed at a given index.

Index should be the first parameter in the function. It is allowed to make the index a Core::OptionalType<>.

The @index tag can also be used to mark an event parameter to be indexed, so clients can subscribe to the event for a specific value of that indexed parameter: for more info see here

As for a short amount of time the @index for events generated code for the JSON-RPC interface that expected a dot (.) as a separator for the index in the clientid instead of a '@' in the designator, @index:deprecated can be put at the indexed event parameter (so instead of just @index) to indicate this indexed event should generate code that uses the old deprecated index format (see the generated documentation for what the interface would be like). Only use this for backwards compatibility reasons.

Example

IController.h sets the @index tag on the index parameter.

This allows the status method to be called as normal to return all plugin configs:

Request

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "Controller.1.status"
}

Or for a specific plugin callsign to be provided after an @ symbol to retrieve just the status of that plugin

Request

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "Controller.1.status@TestPlugin"
}

@opaque

Indicates the string parameter contains a JSON document that should not be deserialised and just treated as a string

Example

IController uses @opaque to indicate the plugin configuration should be treated as an opaque JSON object that does not need to be deserialised and should just be treated as a string

@alt

Provide an alternative name for the method. JSON-RPC methods will be generated for both the actual function name and the alternative name

Note: @text, @alt, @deprecated can be used together.

Example

Methods, properties and notifications can be marked by using:

// @alt <alternative_name>
// @alt:deprecated <alternative_deprecated_name>
// @alt:obsolete <alternative_obsolete_name>

IController.h uses @alt for the Reboot() method to generate an alternatively named method called Harakiri (for legacy reasons)

@text

This tag is applicable to enums, method names, method parameters, PoD members and whole interfaces.

When used for an enum value, it will associate the enum values to the given text in the JSON code while keeping the case of the given text as is.
When used for a method name, it will replace the actual method name with the text that is given in the tag while keeping the case of the text as is.
When used for a method parameter, it will replace the parameter name with the text that is given in the tag while keeping the case of the text as is.
When used for a PoD member, it will replace the PoD member name with the text that is given in the tag while keeping the case of the text as is. Please note that the tag must be placed before the ';' following the PoD member name (see the examples below).
When used at interface level it will influence the casing generated for the JSON-RPC for the whole interface (that is Method names, Parameter names, POD member names, Event names and Enum names). The following options can be used with @text at interface level:
- @text:standard generates the names for all elements in the JSON-RPC interface according the "standard" convention (camelCase for everything except enums which are UPPER_SNAKE). If nothing is specified the default is used (which is if not overridden with the commandline parameter --case-convention, see below, is "standard")
- @text:keep keeps the names for all elements as is in the header file for the JSONRPC interface
- @text:legacy (or as an alternative @text:legacy_lowercase) generates the names for all elements in the JSON-RPC interface to be completely lowercase and PascalCase for enums (this used to be convention for Thunder 5.1 and older).
- @text:custom allows influencing the generation of the casing in the JSON-RPC interface per element. The format to use is @text:custom=< METHODS >,< EVENTS >,< PARAMETERS >,< MEMBERS >,< ENUMS > where allowed values are "lower", "upper", "lowersnake", uppersnake", "camel", "pascal", "keep". See the example section below for more information as well.

Please note that of course the interface designer is responsible for making the interface compliant and consistent with the interface casing guidelines in use (even more perhaps when using @text at interface level as now the whole interface is influenced).

The following commandline options for the JSON-RPC generator are available to also influence the casing used for the generated JSON-RPC code: * "--case-convention < CONVENTION >" selects the default convention to be used on interface level, if not passed the generator will use "standard". Possible values: standard, keep and legacy. * "--ignore-source-case-convention" will make the generator ignore the @text set at interface level

Example

IBrowser.h uses this tag for enum. The generated code for this header will map the text for these enums as allowed and not as Allowed, blocked and not as Blocked.

Without these tags the string equivalent of the enums will be first letter caps followed by all small. This tag has changed it to all small.

IDolby.h uses this tag for method names. The generated code for this header will map the text for this method to the name 'soundmodechanged'. As can be seen @text can be combined with @alt if needed so in this case in the JSON-RPC interface this method can be called with both 'soundmodechanged' as well as 'dolby_audiomodechanged'

In this example the names for PoD member 'One' will be mapped to 'First' and 'Two' will be mapped to 'Second' in the generated code. So in the JSON-RPC interface the JSON container names will be 'First' and 'Second' for these PoD members.

    struct EXTERNAL Example {
        uint32_t One /* @text First */;
        uint32_t Two /* @text Second */;
    };

In this example now for all enums, method names, method parameters and PoD member names the exact name as in the IExample interface will be used in the JSON generated code.

  /* @json 1.0.0 @text:keep */
  struct EXTERNAL IExample : virtual public Core::IUnknown {

In this example now for all method names, method parameters, PoD member names and events will be lowercase in the JSON generated code, enums will be PascalCase

  /* @json 1.0.0 @text:legacy_lowercase */
  struct EXTERNAL IExample : virtual public Core::IUnknown {

In this example now for all method names will be lowercase in the JSON generated code, events will be uppercase, parameters will be lower snake, PoD members will be upper snake and enums will be camel case.

  /* @json 1.0.0 @text:custom=lower,upper,lowersnake,uppersnake,camel */
  struct EXTERNAL IExample : virtual public Core::IUnknown {

@prefix

Use this tag on a class to prepend all JSON-RPC methods with a prefix identifier. This is an alternative to using multiple @text tags.

In this example, all registered methods would contain the prefix source:: This is particularly useful for avoiding clashes, especially if several interfaces are implemented by the same plugin.

// @json 1.0.0
// @prefix source
struct EXTERNAL ISource: virtual public Core::IUnknown {

@statuslistener

Use this tag, to receive notifications when a JSON-RPC client has registered (or unregistered) from a notification.

For more details, click here

@async

Use this tag, to indicate a method on the COM-RPC interface should lead to an asynchronous JSON-RPC function, meaning the completion of the functionality triggered by calling the function is not achieved when the method returns but when a specific event is sent to indicate this.

For more details, click here

@encode

This tag encodes or decodes (if an input parameter) data into/from an alternate format.

@encode:base64 encodes/decodes arrays (or std::vector or ptr+len buffers) as base64 JSON-RPC string, on the condition that the array base is type uint8_t or char.
@encode:hex encodes/decodes arrays (or std::vector or ptr+len buffers) as a Hex JSON-RPC string, on the condition that the array base is type uint8_t or char.

@encode:autolookup is another form of encode: it indicates this interface is used as an object in another interface. See for more info here

An alternative to "autolookup" is custom lookup where one can keep track of how an object-id is connected to an object in a custom manor (in autolookup this is automatic and arranged for you under the hood). Custom lookup is indicated with the @encode:lookup tag. See for more info on custom object lookup here

For COM-RPC @encode:text can be used to have conversion code created for an enum (enum to string and vice versa), this can useful for example in case the enum must be added to a Trace or message as string. Example:

 // @encode:text
        enum state : uint16_t {
            PLAYING = 0x0001,
            STOPPED = 0x0002,
            SUSPENDING = 0x0004
        };

Example

In this example, C-Style uint8_t arrays are encoded as base64.

struct Fixated {
    struct BlueToothInfo {
        uint8_t Addr[6] /* encode:base64 */;
        uint32_t UUIDs[8];
        string Descriptions[8];
    };

Bluetooth BtAddr[5];
uint8_t Edid[128] /*encode:base64 */;
};

In IDisplayInfo.h, the EDID data parameter is encoded.

@encode:bitmask encodes enumerator lists into into a bit mask.

Example

In this example, a tagged enum is treated as a bitmasked list.

enum soundmode : uint8_t {
    MONO = 1,
    STEREO = 2,
    SURROUND = 4
};

virtual Core::hresult SupportedSoundModes(soundmode &sm /* @out @encode:bitmask */) = 0;

Example list: ["mono", "stereo"]

@wrapped

This tag can be placed at class or method level, where at class level is by far preferable as it prevents inconsistencies in JSON-RPC function handling. Wrapped will for a single output parameter also add the parameter name to the result, making it always a JSON object. Note can also be used for array, std::vector, iterator etc. single output parameter. As for a POD it does not immediately make sense to have it wrapped, it becomes a JSON object inside an object, wrapped will be ignored for POD when the wrapped is put on class level. If put on method level however the POD is wrapped as that than is the clear expectation of the interface designer. Wrapped cannot be used for properties as that does not make sense. Incorrect or inconsistent usage will lead to an error raised by the code generators. Of course the documentation generators do take the wrapped tag into account.

Remark: of course it is preferable to keep the JSON-RPC interface as whole consistent so for that reason be hesitant when using this tag (it was added as there are interface where workarounds are used to achieve the wrapped effect).

Example

Without the wrapped tag in case of a single output parameter the result will be as short as possible to make it as efficient as possible:

e.g. with this interface (without wrapped):

    // @json 1.0.0 
    struct EXTERNAL ITest : virtual public Core::IUnknown {

        enum { ID = ID_TEST };

        virtual Core::hresult Test(uint8_t& test /* @out */ ) const = 0;
    };

this is the returned JSON-RPC result for the Test function

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": 0
}

if we enable the wrapped tag for this interface:

    // @json 1.0.0 @wrapped
    struct EXTERNAL ITest : virtual public Core::IUnknown {

        enum { ID = ID_TEST };

        virtual Core::hresult Test(uint8_t& test /* @out */ ) const = 0;
    };

the returned JSON-RPC result for the Test function has changed to this:

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "test": 0
  }
}

Tag	Short Description	StubGen	JsonGen	Scope
@sourcelocation	Sets source location link to be used in the documentation	No	Yes	Class
@deprecated	Marks a method/property/notification deprecated (i.e. obsolete and candidate for removal)	No	Yes	Method
@obsolete	Marks a method/property/notification as obsolete	No	Yes	Method
@brief	Specifies brief description method/property/notification or parameter or POD structure member	No	Yes	Method, Method parameter, POD member
@details	Specifies detaild description of a method/property/notification	No	Yes	Method
@param	Provide description for method/notification parameter or property/notification index	No	Yes	Method
@retval	Specifies possible return error codes for method/property (can be many)	No	Yes	Method
@pre	Allows you to specify the preconditions for a method (documentation only)	No	Yes	Method
@post	Allows you to specify the postconditions for a method (documentation only)	No	Yes	Method

@sourcelocation

By default, the documentation generator will add links to the implemented interface definitions.

The link used by default is https://github.com/rdkcentral/ThunderInterfaces/blob/{revision}/jsonrpc/{interfacefile} (as set in ThunderInterfaces/jsonrpc/common.json)

The @sourcelocation tag allows changing this to a custom URL

Example

@sourcelocation http://example.com

@deprecated

This tag is used to mark a Method, Property as deprecated in the generated document.

Example

When a method is marked with this tag, in the generated .md documentation, it will be marked with the below Message

This API is deprecated and may be removed in the future. It is no longer recommended for use in new implementations.

@obsolete

This tag is used to mark a Method, Property as obolete in the generated document.

Example

When a method is marked with this tag, in the generated .md documentation, it will be marked with the below Message

This API is obsolete. It is no longer recommended for use in new implementations

@brief

This is a short description about the function. This description will be appeneded to the method description in the JSON-RPC generated file.

Example

IDolby.h mentions a brief descrption using this tag.

JsonGenerator.py will create a file JDolbyOutput.h. In that file the method AtmosMetadata. It adds that description.

// Property: dolby_atmosmetadata - Atmos capabilities of Sink (r/o)
module.Register<void, Core::JSON::Boolean>(_T("dolby_atmosmetadata"),
    [_destination](Core::JSON::Boolean& Result) -> uint32_t {
        uint32_t _errorCode;

        // read-only property get
        bool result{};
        _errorCode = _destination->AtmosMetadata(result);

        if (_errorCode == Core::ERROR_NONE) {
            Result = result;
        }
        return (_errorCode);
    });

@details

Just like @brief starts a brief description, @details starts the detailed description. This tag will be used while creating markdown documents for the header.

There it will be captured in the description section for the method. This description will not be added in the code generation.

It will be added only in the document generation.

@param

The syntax for this tag is @param <PARAMETER>. It is associated with a function/property. This tag adds the description about the specified parameter in the generated code and in the generated document.

Example

IDolby.h add description about enable parameter using this tag.

@retval

This tag is used in document creation.

The syntax for this tag is @retval <ErrorCode>: <Description>. It is associated with function/property

This tag adds description about each return codes specified in the generated markdown document.

Example

In IVolumeControl.h, it uses this tag to add description about the returned error code.

@precondition

This tag is used in document creation.

The syntax for this tag is @precondition <Description>. It is associated with function/property

This tag adds description about the preconditions required before calling this function\property

@postcondition

This tag is used in document creation.

The syntax for this tag is @postcondition <Description>. It is associated with function/property

This tag adds description about the postconditions reached after calling this function\property

Tags

Summary

General purpose tags

@stubgen:skip

Example

@stop

@stubgen:omit

Example

@omit

@stubgen:include

Example

@stubgen:stub

Example

@stub

@insert

@define

Example

Parameter Related Tags

@in

Example

@out

Example

@inout

Example

@restrict

Example

@interface

Example

@length

Example

@maxlength

Example

@default

Example

JSON-RPC Related Tags

@json

Example

@json:omit

Example

@uncompliant:extended

@uncompliant:collapsed

@compliant

@event

Example

@property

Example

@iterator

Example

@bitmask

Example

@index

Example

@opaque

Example

@alt

Example

@text

Example

@prefix

@statuslistener

@async

@encode

Example

Example

@wrapped

Example

JSON-RPC Documentation Related Tags

@sourcelocation

Example

@deprecated

Example

@obsolete

Example

@brief

Example

@details

@param

Example

@retval

Example