[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Proper use of deftypemethod and the like

From: Akim Demaille
Subject: Proper use of deftypemethod and the like
Date: Wed, 6 Nov 2019 18:32:20 +0100

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.


          @deftypefn {Library Function} int foobar @
            (int @var{foo}, float @var{bar})
          @end deftypefn

where the type is no longer in @code, but the arguments are in @var.

Given the output in HTML/PDF, I believe neither is correct.  See for instance page 167.  It renders this definition

@deftypemethod {position} {void} initialize (std::string* @var{file} = nullptr, int @var{line} = 1, int @var{col} = 1)
Reset the position to the given values.
@end deftypemethod

as follows (but I fear this attachment will be filtered out by the mailing list):

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.


reply via email to

[Prev in Thread] Current Thread [Next in Thread]