(doc) minor clarifications to nonblock/tgthint

doc/arcantarget_hint.lua

@@ -10,8 +10,11 @@
 -- Otherwise it is expected that *fsrv* references a valid frameserver tied
 -- to a valid source from ref:define_arcantarget or retrieved through the
 -- _adopt event handler.
--- The currently supported ones are: input_label and the format of the
--- *hint* table matches that of the description in ref:launch_target.
+-- The currently supported ones are:
+-- * input_label and the format of the *hint* table matches that of the description in ref:launch_target.
+-- * ident with a string:message field in *hint*, provided as the new segment runtime identity (e.g. document name)
+-- * alert with a string:message field in *hint*, provided as the reason for user attention
+-- * statesize with a int:size field in *hint*, provided as the estimated current output size of a state-save
 -- @group: targetcontrol
 -- @cfunction: arcantargethint
 -- @related:

doc/open_nonblock.lua

@@ -80,7 +80,9 @@
 -- callback is triggered from a state where calls that would alter graphics
 -- pipeline state are permitted or would trigger undefined behaviour. This is
 -- likely to be set as the scheduler will try to defer I/O operations to when
--- it is blocked on rendering or scanning out to a display.
+-- it is blocked on rendering or scanning out to a display. If processing the
+-- data would cause modifications to the rendering pipeline state, it should
+-- then be buffered and handled in the preframe_pulse event handler.
 --
 -- Some files support absolute and/or relative seeking. For relative seeking
 -- based on the current file position, call :seek(ofs):bool,int. To set an