Reißner Ernst wrote:
[...]
All of these markup is not presentational like @table, it is content markup, descriptive or even procedural.
It allows other tools not only to render, but to analyze and to verify.
I also strongly disagree that this kind of markup is really language specific.
Parameters, returns and exceptions are present in all usual languages.
Parameters are always named.
They are not named at all in Forth. They are simply relative positions
on the stack. (They could be named in a comment or documentation, but
this has no meaning in the language itself.)
In the other direction, in Objective-C, parameter names are part of
method names; two methods with the same parameters in a different order
are distinct methods. In Common Lisp, parameters can be positional or
tagged; the order of tagged parameters is not significant in a call. In
Perl, tagged parameters are sometimes emulated by constructing an
associative array from the argument list.
Exceptions may have a type or not,
Only return values are somehow a bit inhomogeneous:
Most language allow a single return value, others allow multiple ones.
Some have named return like parameters.
But all in all I think one could reach easily a uniform set of markup serving 98% of languages.
Overall, this does seem somewhat reasonable, and we could probably cover
all or nearly all languages with a fairly simple model. The existing
@deffn and @deftypefn functions already take names for arguments and a
return type in the latter case. As I understand, convention is to
describe the return value using a sentence "Return ..." or "Returns
..."; both of these are fine in free text.
While writing the above, I noticed that we seem to already be almost all
of the way there. Are you requesting some kind of semantic parameter
table be added? Just name/description pairs? The parameter types are
already in the argument list with @deftypefn and its derivatives. Why
not simply use "@table @var" for this purpose?
-- Jacob
