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