https://bugs.documentfoundation.org/show_bug.cgi?id=168155
Bug ID: 168155
Summary: Add documentation support for Codemaker tools
Product: LibreOffice
Version: Inherited From OOo
Hardware: All
OS: All
Status: UNCONFIRMED
Severity: normal
Priority: medium
Component: sdk
Assignee: [email protected]
Reporter: [email protected]
Created attachment 202558
--> https://bugs.documentfoundation.org/attachment.cgi?id=202558&action=edit
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
--
You are receiving this mail because:
You are the assignee for the bug.
