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''' some_dir_name

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''' 1

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