Re: Feature request: api docs

[Patrice Dumas]

On Mon, Feb 07, 2022 at 08:37:15AM +0000, Reißner Ernst wrote:
> I must correct myself: @result and @error are not usable, 
> Because it has also semantics and within apidocs this would be misuse. 
> I think @param, @return and @throws would be fine at least for functions. 
> The above shall be to describe sth, like so: 
> @return the return value is the @var{n} th prime number @end return
> @param someparamname is the list of names in the database @end param
> @throws totaldesasterexception in case of a total disaster @end throws 

This does not seems ok for several reasons.  First it is not very semantic.
There is no structure, which makes it less appealing than a @*table
or @heading based structure.  Then it is not good Texinfo syntax.  The
Texinfo syntax of a block command would be

@return
the return value is the @var{n} th prime number
@end return

But a block command is in general not the way to go for a formatting
that is more like key, values with possible extended text.  Using @table
in those cases looks better to me. 

@table @asis
@item Return value
The return value is the @var{n} th prime number.

@item Parameters
@table @code
@item @var{x}, @var{y}: @code{float}
The point's coordinate.
@end table
@end table


It could be possible to have @return being a kind of table, with
variable name and type as @item and explanation as text.  But I do not
think that it is wise, it adds a very specific command while not really
solving the need to add more semantics.  I am doubtful that having
specific @-commands is better than using already existing @-commands
with semantics corresponding to @item or @heading.  The issue is most
probably more the possibility to parse fragments of Texinfo code in
different languages, such that the language doing some analysis of the
code can also do the analysis of the API documentation in Texinfo.

-- 
Pat