This is a first cut at some documentation for [CriTcl].  It will hopefully improve over time.
----
'''::critcl::cinit text exts'''

inject $text C code as is, to be executed at extension-init time
inject $exts C code as is, in a different place
(''sets code($file,init) $text and code($file,ext) $exts'')

'''::critcl::ccode text'''

inject $text C code as is (#includes, #defines, common defs, etc)
at the top of the generated code

'''::critcl::cdata name anydata'''

Creates a proc [[name]] which when called will return anydata (as byte array)

'''::critcl::cproc name adefs rtype body'''

Define a C procedure which can be called from Tcl
cproc lets you define a C proc $name, with C code as $body.
Args ($adefs) and return values ($rtype) must be typed.

There are no default args or ways to pass more sophisticated data items than
int/long/float/double/char* for now.

The return type can be ''string'', meaning it's a Tcl_Alloc'ed char* which
will at some point be Tcl_Free'd.

You can also use Tcl_Obj* args (no refcount change),
or return it (in which case it will be decref'ed).

If the first parameter to a cproc has type ''Tcl_Interp*'', that'll be passed in.

Lastly, if the return type is ''ok'', then an int return code of type TCL_OK/TCL_ERROR
is expected and will be processed as usual (errors must set the result, so
it is most likely that you'll also want to specify the Tcl_Interp* arg).

'''adef''': 

   * Tcl_Interp*
   * int
   * long
   * float
   * double
   * char*
   * Tcl_Obj*
   * void*

'''rtype''':

   * void -
   * ok -
   * int -
   * long -
   * float -
   * double -
   * char* - TCL_STATIC char*
   * string - TCL_DYNAMIC char*
   * dstring - TCL_DYNAMIC char*
   * vstring - TCL_VOLATILE char* 
   * default - Tcl_Obj*

'''::critcl::ccommand name anames {-clientdata data} {-delproc proc} args'''

Connects code to the Tcl_CreateObjCommand without further wrapping
ties code to the Tcl_CreateObjCommand without further wrapping

   -clientdata:   client data to be passed
   -delproc:   client delete process

anames {clientdata interp objc objv} are the default argument names.

'''::critcl::csources file ...'''

Additional source files passed to the compiler on the cmd line
(''sets code($file,srcs) $args'')

'''::critcl::cheaders file ...'''

set up file(s) to be available in compiles (also: "dir/*.h")
If "critcl::cheaders -g" is given, then the output file is not stripped
and the "-DNDEBUG" flag is not added to the gcc command line.
(''sets code($file,hdrs) $args'')

'''::critcl::clibraries file ...'''

additional libraries (args such as "-l..." are passed on as is)
(''sets code($file,libs) $args'')

----
'''::critcl::failed'''

check if the C compile failed

'''::critcl::done'''

stub - does nothing

'''::critcl::tk'''

configures tk 1

'''::critcl::cache'''

returns the [CriTcl Cache] directory for the current platform

'''::critcl::tsources'''

does nothing

'''::critcl::platform'''

return a platform descriptor ($OS-$machine)
of the platform CriTcl is being run on

'''::critcl::compiling'''

check that we can indeed run a compiler

'''::critcl::sharedlibext'''

returns the shared library extension for the target platform.

'''::critcl::scripting'''

inverse of [[::critcl::compiling]] - we can't run a compiler
----
'''::critcl::config option value'''

'''outdir ""'''

the compiled library will be saved for permanent use if the outdir
option is set (in which case rebuilds will no longer be automatic)

'''keepsrc 0'''

the generated source will be kept (default: delete it)
The intermediate C code generated by CriTcl can be kept around by doing:

'''combine ""'''

   "":   gcc -shared -DUSE_TCL_STUBS -O2 -DNDEBUG -Wl,-s - no -fPIC ... -g in cmdline stops this
   dynamic:   -fPIC 
   static:   no -fPIC
   standalone:   no -fPIC, no -DUSE_TCL_STUBS

'''appinit ""'''

No meaning

'''force 0'''

force recompilation

'''I ""'''

adds -I to command line

'''L ""'''

no meaning

'''tk 0'''

compile for tk

'''language ""'''

-x options