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.
Elsewhere:
@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
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
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!
