Am 04.12.2011 21:16, schrieb Bruno Le Floch:

>> Yes, there are a few cases where such a convention would not be
>> sufficient, for example \prop_(g)get:NnN. As I said, this mirrors the
>> situation with TF functions, where there are a few in which the
>> documentation does have to cover more complex situations on a
>> case-by-case basis.
> Side note: \prop_gget:NnN doesn't and shouldn't exist. We may want to
> add somewhere a mention that 'pop' and 'gpop' functions always return
> their value locally.

agreed, we decided long ago that all "get" or "pop" would be local in 
their return value and only in case of "pop" the change to the 
underlying data structure could be global.

So yes that should probably better documented up front as well.

> =
> Where functions for variable manipulation can [perform assignments]
> either locally or
> globally, the latter case is indicated by the inclusion of a "g" in the
> [second part] of the function name. Thus \tl_set:Nn is a local function but
> \tl_gset:Nn acts globally. Functions of this type are always documented
> together, and the scope of action may therefore be inferred from the
> presence or absence of a "g".

sounds good to me