module xdc.tools.cdoc.Example

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
    enum {
        Example_LOOP,
        Example_PRINT
    } ;
 
        Example_AVALUE
    } Example_AnEnum;
 
        Example_ATypedEnum cmdId;
        union {
            struct {
                Int count;
            } loop;
            struct {
                String msg;
            } print;
        } args;
    } Example_ACmd;
 
        Int aField;
    } Example_AStruct;
 
        String aString;
        Int anInt;
    } Example_AUnion;
module-wide config parameters
module-wide functions
module-wide built-ins
 
XDCscript usage meta-domain
var Example = xdc.useModule('xdc.tools.cdoc.Example');
module-wide constants & types
        const Example.LOOP;
        const Example.PRINT;
 
        const Example.AVALUE;
 
        obj.cmdId = Example.ATypedEnum  ...
        obj.args = Example.__struct__1  ...
 
        obj.aField = Int  ...
 
        obj.aString = String  ...
module-wide config parameters
        aString: 'hello',
        anInt: 1234
    };
 
 
XDCspec declarations sourced in xdc/tools/cdoc/Example.xdc
package xdc.tools.cdoc;
 
module Example {
module-wide constants & types
        LOOP,
        PRINT
    };
 
        AVALUE
    };
 
        Example.ATypedEnum cmdId;
        union {
            struct {
                Int count;
            } loop;
            struct {
                String msg;
            } print;
        } args;
    };
 
        Int aField;
    };
 
        String aString;
        Int anInt;
    };
module-wide config parameters
        aString: 'hello',
        anInt: 1234
    };
 
module-wide functions
    Void aFunction// Example function documentation( Int aParam );
}
 
enum Example.ATypedEnum

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

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

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

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

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

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

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

Example function documentation

C synopsis target-domain
Void Example_aFunction( Int aParam );
 
ARGUMENTS
aParam — example function parameter documentation
 
module-wide built-ins

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