[doc] add comments to the header file

Note that several comments are still missing, specifically for the
area's acquire()/release()/available() routines, the function of which
is not clear to me.