Fixing Doxygen Module descriptions

Here's the place for discussion related to coding in FreeCAD, C++ or Python. Design, interfaces and structures.
User avatar
Kunda1
Posts: 6441
Joined: Thu Jan 05, 2017 9:03 pm

Fixing Doxygen Module descriptions

Postby Kunda1 » Sat Sep 28, 2019 9:32 pm

So I've started to go through and attempt to fix the state of the https://www.freecadweb.org/api/modules.html page.
The branch I'm working on is here

My PR is pretty messy ATM because I was trying to understand the format of how to structure the descriptions, and I changed my mind several times over the period of editing. So of course I'll go back and make them all uniform one I get more feedback on what the community prefers.

The information comes from *.dox files that exist throughout the codebase and they are incomplete. Specifically, not only the top level dox files are incomplete, but their sub-directory counterpart .dox files are missing. I don't know the level of refinement we want to go in to, learning this as I go. So feedback is essential.

BTW...I wish I would of found this text when I started but nevertheless, it's helpful now:

source: https://github.com/FreeCAD/FreeCAD/blob ... od/mod.dox
** \addtogroup WORKBENCHES
Most of FreeCAD's functionality is defined in dedicated Workbenches

Those plugins, also called \b modules or \b worbenches, provide
functionality for specialized facets of FreeCAD. The word \b module
refers to any new group of tools, while \b workbench designates
specifically a GUI group of tools in the FreeCAD interface. All
workbenches are defined in modules, but not all modules contain a
workbench. Practically, though, all the main modules define a
workbench with the same name, so the terms are almost interchangeable.

Some of these modules are programmed in C++, others in Python, and some
in a mixture of C++ and Python.

*/

/** \defgroup CWORKBENCHES C++ workbenches
* \ingroup WORKBENCHES
* \brief These workbenches are programmed primarily in C++, but most provide a Python API as well.
*/

/** \defgroup PYTHONWORKBENCHES Python workbenches
* \ingroup WORKBENCHES
* \brief Those are workbenches programmed primarily in Python
*/

/** \defgroup UTILITIES Utility modules
* \ingroup WORKBENCHES
* \brief Modules that provide utility tools to FreeCAD but don't define a workbench
*/
Want to contribute back to FC? Checkout:
#lowhangingfruit | Use the Source, Luke. | How to Help FreeCAD | How to report FC bugs and features
vocx
Posts: 2830
Joined: Thu Oct 18, 2018 9:18 pm

Re: Fixing Doxygen Module descriptions

Postby vocx » Sat Sep 28, 2019 10:13 pm

Kunda1 wrote:
Sat Sep 28, 2019 9:32 pm
...
The information comes from *.dox files that exist throughout the codebase and they are incomplete. Specifically, not only the top level dox files are incomplete, but their sub-directory counterpart .dox files are missing.
...
This is the thing, the way Doxygen works, is that you add documentation text inside the source files themselves, that is, inside .h, .cpp, .py, etc.

Then Doxygen will parse the sources, parse the documentation strings, check function prototypes, and build the documentation based on that information. In general, it should not be necessary to add external files, like .dox files. Why? Because if the source changes, you also have to change any external .dox file that may have outdated information. Therefore it is much better to update only the source file itself.

In C++ Doxygen works quite well because of the strict typing system. Headers help indicate which functions are used in another file, and thus relationships between the different files can be easily established.

The problem with FreeCAD is that the source is a mix of C++ and Python, so this relationship is not traditional. Many Python functions are created in C++, and are available only at run time, without a corresponding .py file.

Therefore, adding external .dox files kinda makes sense to document Python functions, but C++ files probably don't require them absolutely.

Also, you need to check the Doxygen configuration file. This file has a ton of options. Maybe modifying some of these options would improve the current state of the documentation without having to do major changes, or adding more .dox files. The options of the configuration file, called BuildDevDoc.cfg.in, may automatically give you more module levels and things like that.

Also, remember that https://www.freecadweb.org/api is incomplete. This generated documentation is stripped from many things to make it small (600 MB), so it can be hosted online. The full documentation that can be produced offline from the sources is 4.5 GB in size.

See source documentation and Doxygen.
Last edited by vocx on Mon Sep 30, 2019 4:30 pm, edited 2 times in total.
To support the documentation effort, and code development, your donation is appreciated: paypal.
User avatar
Kunda1
Posts: 6441
Joined: Thu Jan 05, 2017 9:03 pm

Re: Fixing Doxygen Module descriptions

Postby Kunda1 » Sun Sep 29, 2019 8:06 pm

ugh... this is a little overwhelming, to be honest.
Want to contribute back to FC? Checkout:
#lowhangingfruit | Use the Source, Luke. | How to Help FreeCAD | How to report FC bugs and features
vocx
Posts: 2830
Joined: Thu Oct 18, 2018 9:18 pm

Re: Fixing Doxygen Module descriptions

Postby vocx » Mon Sep 30, 2019 2:53 am

Kunda1 wrote:
Sun Sep 29, 2019 8:06 pm
ugh... this is a little overwhelming, to be honest.
It is. It is not something you causally attempt one weekend.

If you want to start something, my recommendation is to try to update the Doxygen configuration file BuildDevDoc.cfg.in. It has a lot of tags (variables), so it would be interesting to see which can be added, or changed. Also, I think the generated documentation uses custom stylesheets (.css, .html, where are they?) for the generated HTML pages, so maybe these templates can also be modified to improve aesthetically the HTML pages. This doesn't require a lot of programming knowledge, it's mostly tedious work.

You can generate a basic configuration file, and then compare it with FreeCAD's BuildDevDoc.cfg.in.

Code: Select all

doxygen -g
As compiling the entire documentation may take a long time, I'd also suggest using a scaled down version of the source code to test changes. Say, take the core code in src/App, src/Base, src/Gui, and a couple of workbenches, like Part and FEM (something that has Python code), and see how the documentation is generated from that. Once you can see that the documentation is produced as you want, you can extend the tricks to the entire source code.
To support the documentation effort, and code development, your donation is appreciated: paypal.