Re: AW: Feature request: api docs

[Jacob Bachmeyer]

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