Improve C++ API Documentation

[pieterhijma]

Proposal description

The essence of the proposal is to 1) improve the quality for the C++ API Documentation and 2) to make the C++ API Documentation complete. My proposal is to focus on namespace App since I am already fairly familiar with it and it is arguably the most important part of FreeCAD. This project can run in conjunction with the GSoC project that focuses on improving the API documentation in general.

The proposed changes are standardizing doxy comments with @brief, a detailed explanation, and @param and @return for every public and protected function.

This will benefit the FreeCAD project because:

• good documentation may attract more developers to improve FreeCAD,
• it can help maintainers to judge PRs better, and
• it sets a standard for PRs, allowing FreeCAD's documentation to improve over time.

Deliverables

• Defining a standard for documentation: documented on the wiki and other relevant places.
• Apply the standard to namespace App on the existing documentation: PRs for well-defined sets of files.
• Add missing documentation in namespace App: PRs for well-defined sets of files

Timeline

• Define a documentation standard in collaboration with the community / GSoC project: Start in May, finish end of May
• Apply the standard to files in namespace App: Start in June, finish end December

Risks and mitigation

I would like to carry out this work as an independent contractor.

The risk entails the estimation of work since only namespace App contains about 50k lines of code. Since some parts are already well documented while others are not documented at all, it is difficult to estimate the amount of work.

Compensation

I would like to carry out this work with for a total of 8000 EUR.

About you

My name is Pieter Hijma (pieterhijma on the forum and pieterhijma on GitHub). I'm an independent contractor (https://pieterhijma.net) and as a co-founder of the Open Toolchain Foundation, I would love to contribute to improve FreeCAD as it is an important part of open toolchains.

This project finds it motivation from my work on variable sets as improved API documentation would have helped my work. In general, I have a strong interest in documentation, often using literate programming as a way to document code, and I have also worked on automating assembly instructions for Open Source Hardware. With a Computer Science PhD, I am in a good position to document this important part of FreeCAD. I've already made a small (but high quality) contribution to FreeCAD's documentation in this PR.

[chennes]

Hello @pieterhijma -

Thank you for your grant proposal submission. The FPA would like to ask for a delay on this proposal: improving the API documentation is one of this year's potential Google Summer of Code projects, and we'd prefer to consider your grant either after, or at least concurrently with, that project. Would you consider allowing us to put it on hold until the GSoC project is underway (or is not selected)?

[pieterhijma]

Hi @chennes,

Sure, I can understand. That is no problem for me.