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
Documentation of @code{foo}.
@end deftypefn
where the type of the argument is in @code, while the argument itself is naked.
Elsewhere:
@deftypefn {Library Function} int foobar @
(int @var{foo}, float @var{bar})
...
@end deftypefn
(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 https://www.gnu.org/software/bison/manual/bison.pdf 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
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.
Cheers!