Created attachment 202558 [details]
XAccessible Python stub file generated by pythonmaker

Description:
Codemaker tools, including cppumaker, javamaker, netmaker and recently, pythonmaker are the tools that are used to generate language specific representations of the IDL files.

Language Code Generators for UNOIDL Entities
https://docs.libreoffice.org/codemaker.html

They are useful for different purposes:

The output from codemaker tools are useful for different purposes: In C++/Java, they are needed to write code that uses LibreOffice API. In Python, one needs them to have auto-completion in an IDE.

On the other hand, codemaker tools currently lack the ability to process the documentation comments inside IDL code, and turn them into appropriate documentation output. This is what Doxygen does for generating HTML documentation.

For example, consider XAccessible interface in LibreOffice:

XAccessible Interface Reference
https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1accessibility_1_1XAccessible.html

If you try generating the same documentation with either of the codemaker tools, you will see that it lacks the documentation.

To compare, this is the Python stub files generated by processing the doxygen output. (Thanks to Paul, the author of the package)
https://github.com/Amourspirit/python-ooouno/tree/main/ooo

The relevant stub file is:
https://github.com/Amourspirit/python-ooouno/blob/main/ooo/lo/accessibility/x_accessible.py

There are also some additional type information available in the above file. These are the definitions for Accessible:
    __ooo_full_ns__: str = 'com.sun.star.accessibility.XAccessible'
    __ooo_type_name__: str = 'interface'
    __pyunointerface__: str = 'com.sun.star.accessibility.XAccessible'

The difference is more visible in the bigger IDL files, for example consider XReportControlFormat:

https://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1report_1_1XReportControlFormat.html

https://github.com/Amourspirit/python-ooouno/blob/main/ooo/lo/report/x_report_control_format.py

Using the above Python stub files with documentation, shows better usability in a Python IDE by providing relevant documentation for the services, interfaces, functions and other symbols.

I have attached the output generated by pythonmaker, which lacks ability to generate documentation.

The implementation should be able to process simple tags like <b>, <i>, <em> and also should create links to the api.libreoffice.org for further information provided by @see: tags.

For more information on the documentation syntax inside the code, see:
https://www.doxygen.nl/manual/docblocks.html