On Fri, Feb 4, 2022 at 2:18 PM Reißner Ernst <[email protected]> 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.
