module xdc.tools.cdoc.Example
index URL

XDOC markup language examples for modules and interfaces

This module demonstrates the features of XDOC on the declarations of an XDC module. View the source text of this .xdc file for details on how to use these examples.
C synopsis target-domain sourced in xdc/tools/cdoc/Example.xdc
#include <xdc/tools/cdoc/Example.h>
Functions
Void 
Example_aFunction// Example function documentation(Int aParam);
Functions common to all target modules
Example_Module_getMask// Returns the diagnostics mask for this module, Example_Module_hasMask// Test whether this module has a diagnostics mask, Example_Module_heap// The heap from which this module allocates memory, Example_Module_id// Get this module's unique id, Example_Module_setMask// Set the diagnostics mask for this module, Example_Module_startupDone// Test if this module has completed startup
Typedefs
typedef struct
Example_ACmd// Example "tagged union" documentation ...
typedef enum
Example_AnEnum// Example enum documentation ...
typedef struct
Example_AStruct// Example structure declaration ...
typedef Int
Example_ATypedEnum// Example typed enumeration;
typedef union
Example_AUnion// Example union documentation ...
Constants
extern const Example_AUnion 
Example_u// Example statically initialized union documentation;
 
enum Example_ATypedEnum
index URL

Example typed enumeration

C synopsis target-domain
typedef Int Example_ATypedEnum;
enum {
    Example_LOOP,
    Example_PRINT
} ;
VALUES
LOOP — example "typed" enum value documentation
DETAILS
This declaration defines a new type named ATypedEnum which is an alias of Int and two constants of type ATypedEnum.
Unlike ordinary C enums, where the compiler is free to choose an arbitrary type for enums, this declaration ensures that the new type is of a specific named type (in this case, Int).
enum Example_AnEnum
index URL

Example enum documentation

C synopsis target-domain
typedef enum Example_AnEnum {
    Example_AVALUE
} Example_AnEnum;
VALUES
AVALUE — example enum value documentation
struct Example_ACmd
index URL

Example "tagged union" documentation

C synopsis target-domain
typedef struct Example_ACmd {
    Example_ATypedEnum cmdId;
    union {
        struct {
            Int count;
        } loop;
        struct {
            String msg;
        } print;
    } args;
} Example_ACmd;
FIELDS
args — example structure field documentation
DETAILS
This structure illustrates the "tagged union" pattern: one field of the structure indicates how to interpret the rest of the structure.
struct Example_AStruct
index URL

Example structure declaration

C synopsis target-domain
typedef struct Example_AStruct {
    Int aField;
} Example_AStruct;
FIELDS
aField — example field documentation
union Example_AUnion
index URL

Example union documentation

C synopsis target-domain
typedef union Example_AUnion {
    String aString;
    Int anInt;
} Example_AUnion;
FIELDS
aString — example union field documentation
config Example_u  // module-wide
index URL

Example statically initialized union documentation

C synopsis target-domain
extern const Example_AUnion Example_u;
Example_aFunction()  // module-wide
index URL

Example function documentation

C synopsis target-domain
Void Example_aFunction(Int aParam);
ARGUMENTS
aParam — example function parameter documentation
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Example_Module_id();
// Get this module's unique id
 
Bool Example_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle Example_Module_heap();
// The heap from which this module allocates memory
 
Bool Example_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 Example_Module_getMask();
// Returns the diagnostics mask for this module
 
Void Example_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
 
XDCscript usage meta-domain sourced in xdc/tools/cdoc/Example.xdc
var Example = xdc.useModule('xdc.tools.cdoc.Example');
module-wide constants & types
    values of type Example.ATypedEnum// Example typed enumeration
        const Example.LOOP;
        const Example.PRINT;
    values of type Example.AnEnum// Example enum documentation
        const Example.AVALUE;
    var obj = new Example.ACmd// Example "tagged union" documentation;
        obj.cmdId = Example.ATypedEnum  ...
        obj.args = Example.__struct__1  ...
    var obj = new Example.AStruct// Example structure declaration;
        obj.aField = Int  ...
    var obj = new Example.AUnion// Example union documentation;
        obj.aString = String  ...
module-wide config parameters
    Example.u// Example statically initialized union documentation = Example.AUnion {
        aString: 'hello',
        anInt: 1234
    };
    Example.common$// Common module configuration parameters = Types.Common$ undefined;
 
enum Example.ATypedEnum
index URL

Example typed enumeration

XDCscript usage meta-domain
values of type Example.ATypedEnum
    const Example.LOOP;
    const Example.PRINT;
VALUES
LOOP — example "typed" enum value documentation
DETAILS
This declaration defines a new type named ATypedEnum which is an alias of Int and two constants of type ATypedEnum.
Unlike ordinary C enums, where the compiler is free to choose an arbitrary type for enums, this declaration ensures that the new type is of a specific named type (in this case, Int).
C SYNOPSIS
Example_ATypedEnum
enum Example.AnEnum
index URL

Example enum documentation

XDCscript usage meta-domain
values of type Example.AnEnum
    const Example.AVALUE;
VALUES
AVALUE — example enum value documentation
C SYNOPSIS
Example_AnEnum
struct Example.ACmd
index URL

Example "tagged union" documentation

XDCscript usage meta-domain
var obj = new Example.ACmd;
 
    obj.cmdId = Example.ATypedEnum  ...
    obj.args = Example.__struct__1  ...
FIELDS
args — example structure field documentation
DETAILS
This structure illustrates the "tagged union" pattern: one field of the structure indicates how to interpret the rest of the structure.
C SYNOPSIS
Example_ACmd
struct Example.AStruct
index URL

Example structure declaration

XDCscript usage meta-domain
var obj = new Example.AStruct;
 
    obj.aField = Int  ...
FIELDS
aField — example field documentation
C SYNOPSIS
Example_AStruct
union Example.AUnion
index URL

Example union documentation

XDCscript usage meta-domain
var obj = new Example.AUnion;
 
    obj.aString = String  ...
FIELDS
aString — example union field documentation
C SYNOPSIS
Example_AUnion
config Example.u  // module-wide
index URL

Example statically initialized union documentation

XDCscript usage meta-domain
Example.u = Example.AUnion {
    aString: 'hello',
    anInt: 1234
};
C SYNOPSIS
Example_u
metaonly config Example.common$  // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Example.common$ = Types.Common$ undefined;
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
generated on Tue, 24 Aug 2010 15:39:20 GMT