Re: Feature request: api docs

[Patrice Dumas]

On Fri, Feb 04, 2022 at 08:19:24AM +0000, Reißner Ernst wrote:
> Hello all,
> I know that texinfo offers some commands to document a function which can be 
> used for various computing languages.
> One can document the signature: specify name of function, return variable and 
> input parameters.
> 
> What is missing in my opinion: a way to document the meaning of the input 
> parameters
> And of the return value and documentation of errors/exception.
> There are many api doc systems providing these things, java, c#, 
> c++(doxygen), python(https://developer.lsst.io/python/numpydoc.html)
> And the latter is a good illustration for what I want to say.

It seems to me that what is in the numpydoc specification is somewhat
too specific to be relevant for Texinfo.  However, I also think that we
should make sure that a corresponding formatting can be achieved, even if
without some specific semantic.  It seems to me that almost everything
is available, though I may have missed something.

Within a def*, the sections, such as
Parameters
----------
can be formatted either as 
@subsubheading Parameters

or using a @table

@table @asis

@item Parameters

@table @asis
@item @var{x}: @code{float}, optional
@end table

@item Raises
...

@end table

Summary and Extended summary can appear as text.

It seems to me that Parameters formatting can be achieved with something
like

@table @asis
@item @var{x}: @code{float}, optional
X-axis coordinate.
@item @var{x0} : @code{float}, optional
X-axis coordinate for the second point (the origin, by default).

Descriptions can have multiple paragraphs, and lists:

@itemize @minus
@item First list item.
@item Second list item.
@end itemize

@end table

definition list can also be formatted as a @table too.
Same for returns as for Parameters.

Raises can also be formatted as a @table.

See Also could be normal text with @xref.

There aren't references in Texinfo, but if added, it should be more
generically available, not only for methods documentation.  I think that
this one is in a TODO, actually.

Lastly, there is 
@example for examples.

Of course, all that lacks semantic. One could imagine having, instead of
@table, @parameters, or maybe @ptable which would be formatted like a
table.  An indicator functions for a type, like @type{} to use instead
of @code could also be added.  As the formatting can already be done in
Texinfo, the main issue to me is where to stop in term of semantic
markup.  And I do not think that we should add new markup especially
for the formatting of functions, but with a more general view on the
usefulness of more markup in other contexts too. 

> Also missing: a way to document a class or even a package.
> Texinfo seems not yet arrived in oo world.

I agree that there is nothing existing as a container for multiple @def*
that could be used for class or package.

-- 
Pat