Re: Proper use of deftypemethod and the like

[Gavin Smith]

On Wed, Nov 06, 2019 at 06:32:20PM +0100, Akim Demaille wrote:
> Hi all,
> 
> The documentation is not clear/consistent on how one should document typed 
> functions.  For instance it says:
> 
>      @deftypefn Function int foo (@code{const std::vector<int>@&} bar)
>      Documentation of @code{foo}.
>      @end deftypefn
> 
> where the type of the argument is in @code, while the argument itself is 
> naked.

This is in the "Inserting an Ampersand" node.  I notice in the Info 
output for this there are single quotes output for the @code: this is 
wrong.

> where the return type (void) is in tt style, like the name of the routine 
> (initialize). The arguments are correctly in var style, but the types of the 
> arguments are in italic, which is inconsistent with void.
> 
> 
> Sure, I can use @code for types and @var for argument names, but it seems 
> super heavy.  Is this what is recommended?  If so, I suggest the examples in 
> the doc should be updated.

The manual does say:

     Since in typed languages, the actual names of the arguments are
     typically scattered among data type names and keywords, Texinfo
     cannot find them without help.  You can either (a) write everything
     as straight text, and it will be printed in slanted type; (b) use
     '@var' for the variable names, which will uppercase the variable
     names in Info and use the slanted typewriter font in printed
     output; (c) use '@var' for the variable names and '@code' for the
     type names and keywords, which will be dutifully obeyed.

So it does seem to be as you say.