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.
XDCspec summary sourced in xdc/tools/cdoc/Example.xdc
module Example {  ...
// inherits xdc.runtime.IModule
C synopsis target-domain
#include <xdc/tools/cdoc/Example.h>
module-wide constants & types
    typedef Int Example_ATypedEnum// Example typed enumeration;
    enum {
        Example_LOOP,
        Example_PRINT
    } ;
 
    typedef enum Example_AnEnum// Example enum documentation {
        Example_AVALUE
    } Example_AnEnum;
 
    typedef struct Example_ACmd// Example "tagged union" documentation {
        Example_ATypedEnum cmdId;
        union {
            struct {
                Int count;
            } loop;
            struct {
                String msg;
            } print;
        } args;
    } Example_ACmd;
 
    typedef struct Example_AStruct// Example structure declaration {
        Int aField;
    } Example_AStruct;
 
    typedef union Example_AUnion// Example union documentation {
        String aString;
        Int anInt;
    } Example_AUnion;
module-wide config parameters
    extern const Example_AUnion Example_u// Example statically initialized union documentation;
module-wide functions
    Void Example_aFunction// Example function documentation( Int aParam );
module-wide built-ins
    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// Set the diagnostics mask for this module( Bits16 mask );
 
XDCscript usage meta-domain
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;
 
XDCspec declarations sourced in xdc/tools/cdoc/Example.xdc
package xdc.tools.cdoc;
 
module Example {
module-wide constants & types
    enum ATypedEnum// Example typed enumeration {
        LOOP,
        PRINT
    };
 
    enum AnEnum// Example enum documentation {
        AVALUE
    };
 
    struct ACmd// Example "tagged union" documentation {
        Example.ATypedEnum cmdId;
        union {
            struct {
                Int count;
            } loop;
            struct {
                String msg;
            } print;
        } args;
    };
 
    struct AStruct// Example structure declaration {
        Int aField;
    };
 
    union AUnion// Example union documentation {
        String aString;
        Int anInt;
    };
module-wide config parameters
    config Example.AUnion u// Example statically initialized union documentation = {
        aString: 'hello',
        anInt: 1234
    };
 
    metaonly config Types.Common$ common$// Common module configuration parameters;
module-wide functions
    Void aFunction// Example function documentation( Int aParam );
}
 
enum Example.ATypedEnum
index URL

Example typed enumeration

XDCscript usage meta-domain
values of type Example.ATypedEnum
    const Example.LOOP;
    const Example.PRINT;
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

XDCscript usage meta-domain
values of type Example.AnEnum
    const Example.AVALUE;
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

XDCscript usage meta-domain
var obj = new Example.ACmd;
 
    obj.cmdId = Example.ATypedEnum  ...
    obj.args = Example.__struct__1  ...
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

XDCscript usage meta-domain
var obj = new Example.AStruct;
 
    obj.aField = Int  ...
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

XDCscript usage meta-domain
var obj = new Example.AUnion;
 
    obj.aString = String  ...
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

XDCscript usage meta-domain
Example.u = Example.AUnion {
    aString: 'hello',
    anInt: 1234
};
C synopsis target-domain
extern const Example_AUnion 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.
 
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
generated on Sat, 12 Jun 2010 05:51:41 GMT