Improve C++ API Documentation

pieterhijma commented 8 months ago

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 commented 7 months ago

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 commented 7 months ago

Hi @chennes,

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

chennes commented 5 months ago

The GSOC documentation project was not funded, so now it is no longer necessary to hold this proposal. Are there any changes you'd like to make before I forward it to the Grant Review Committee?

pieterhijma commented 5 months ago

@chennes: Thanks for getting back to me. Originally, this project was seen in the light of the GSoC project. Based on the description of that project, the community also requested/proposed other improvements to the API documentation that I do not consider in the scope of this proposal, for example improve the CSS and splitting Python from C++. Instead, this project only aims to improve the C++ docstrings in the namespace App, primarily to help other developers but also maintainers to help them gain a better understanding of the code. I hope it will also help making the core of FreeCAD more accessible to the community (something I discussed with @yorikvanhavre in light of #3), in this case by means of high-quality docstrings.

I see that in the meantime #9 has been submitted, which is essentially the GSoC project. This project can still be seen as being in conjunction with #9 and I would love to work together as I originally planned with the GSoC. I believe there is more than enough work for both projects.

chennes commented 5 months ago

The FPA Grant Review Committee has evaluated this proposal, and supports funding it. This dovetails well with Grant Proposal #9, and both contributors have already indicated that they intend to collaborate on the work. It's work that few developers are interested in undertaking, and will benefit the entire community of FreeCAD developers (and ultimately users). I have forwarded this recommendation to the full FPA for voting.

pieterhijma commented 5 months ago

That's great news! Thanks to the review committee for the support.

chennes commented 4 months ago

The FPA has voted to approve this grant. Congratulations, @pieterhijma, and thank you for your proposal. Please reach out to wandererfan@freecad.org to set up your banking information.

pieterhijma commented 4 months ago

That's great news! Thanks to the review committee and FPA members.

FreeCAD / FPA-grant-proposals