AW: Feature request: api docs

[Reißner Ernst]

-----Ursprüngliche Nachricht-----
Von: Gavin Smith <gavinsmith0123@gmail.com> 
Gesendet: Freitag, 4. Februar 2022 18:27
An: Reißner Ernst <Ernst.Reissner@corpuls.com>
Cc: bug-texinfo@gnu.org; rei3ner@arcor.de
Betreff: Re: Feature request: api docs

CAUTION: This email originated from outside your organization. Exercise caution 
when opening attachments or on clicking links from unknown senders.


On Fri, Feb 4, 2022 at 2:18 PM Reißner Ernst <Ernst.Reissner@corpuls.com> 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.

>

>

>

> Also missing: a way to document a class or even a package.

>

> Texinfo seems not yet arrived in oo world.

>

>

>

> Any change to get this included?

>

>

>

> I ask because texinfo has many advantages also… above all the many 
> interesting output formats.



> It certainly seems that people don't use Texinfo for this.

Well, I know that octave uses it for api docs. Maybe emacs also but it is hard 
to find out who it uses at all. 
Maybe one shall include a note in the manual and ask to user to give feedback. 
That way one could find out. 

Anyway, there is no doubt, that texinfo is intended to write api docs also. 
Have a look at the manual: 
Section 11.9: @result, @error, maybe @print (as a side effect) 
But above all Section 13 @deffnx and related. 
Anyway, it seems to be somehow lisp-centered and not at all oo. 

@Gavin Smith : the style I know is putting api docs with the code. 
This turned out to be by far safest to keep docs up to date. 
In java world, in c#, in c and c++ I think this is the accepted way to do it. 
Also in lisp and in python... 
I would wonder if also qt api docs wouldn’t be done that way. 
The example 
https://webkitgtk.org/reference/webkit2gtk/stable/index.html 
is really low quality. 
https://docs.oracle.com/javase/7/docs/api/ This is for sure generated from the 
java sources. 


>What could be great, if people had the time for it, is to support some
>project in documenting their API using Texinfo. As Texinfo was
>originally developed mainly for Emacs documentation and was shaped by
>its needs, the needs of documenting some particular project might be a
>better way of making the language more useful.

I agree very much. 

Regards, 
Ernst