On 03/12/2011 11:25, Frank Mittelbach wrote:
> Am 03.12.2011 10:34, schrieb Joseph Wright:
> 
>> I wonder if it would make more sense to take the same approach for
>> functions with local/global versions. Something like:
>>
>> 'Where functions for variable manipulation can apply either locally or
>> globally, the latter case is indicated by the inclusion of a "g" in the
>> last 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".'
>>
>> The scope would then be excluded from the function documentation:
>>
>> % \begin{function}
>> %   {
>> %     \tl_set:Nn,  \tl_set:cn,
>> %     \tl_gset:Nn, \tl_gset:cn
>> %   }
>> %   \begin{syntax}
>> %     \cs{tl_set:Nn} \meta{tl~var} \Arg{tokens}
>> %   \end{syntax}
>> %   Sets \meta{tl~var} to contain \meta{tokens},
>> %   removing any previous content from the variable.
>> % \end{function}
>>
>> Does this make sense as a sensible balance between formality and
>> documentation length?
> 
> I would be quite happy with this approach of documenting local and
> global variants in a single place together as the convention is in
> nearly all cases very clear and the use of "g" or its absence
> understandable without further explanation (other than at the very
> beginning outlining the approach). And in the few cases where the "g"
> may need additional explanation because it could refer to one or the
> other argument that could still either be done on the spot or if
> necessary in that case split into separate documentation blocks.

Hello Frank,

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.
--
Joseph Wright