Re: Feature request: api docs

[Gavin Smith]

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.

I don't have much experience of using object-oriented libraries myself
but the best documented I have used is for the Qt libraries:

e.g
https://doc.qt.io/qt-6/qtcore-index.html
https://doc.qt.io/qt-6/qtransform.html

I couldn't easily find out how they did their documentation and
whether it is generated from C++ source code files or maintained as a
separate file, or both. Does anybody know more?

Documentation that is simply generated from source code files
themselves can be poor, especially if the developers don't put a lot
of effort into it. I'd like to know for quality examples of API
documentation (like the Qt documentation) what it was about the
documentation system, if anything, which supported/encouraged this.
Obviously, the system itself is not enough, as writing quality
documentation is work for people to do.

An example of documentation that looks like it was generated from source files:

https://webkitgtk.org/reference/webkit2gtk/stable/index.html

You end up reading through the documentation of pretty much every
class and function trying to work out how to do something, unsure if
it is even possible.

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.