Re: Proper use of deftypemethod and the like

[Akim Demaille]

Hi Gavin,

> Le 8 nov. 2019 à 22:38, Gavin Smith <address@hidden> a écrit :
> 
> 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.

Bummer, that's also what I observe in Info now :(


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

Wow, that was right below the piece of doc I quoted above...  Thanks for 
pointing this out to me, I had stoped at the example itself.

Good, so it's clear: I should use @code.  But it's broken in Info output :)  Is 
there already an (approximate) release date for the next Texinfo?