[tracking] Improve code documentation

[sgaist]

This ticket is a follow up of today's community meeting.

TLDR: improve the code base documentation so that users of the libraries as well as new (and old) contributors have an easier time going through it.

The longer story: while the libs code base is not void of documentation, it's also not completely documented and there are often a mix of doxygen and documentation formatted as comments (not related to comments in code). This make understanding how things are working more complicated than needed.

As an example of project that is heavily documented: the Qt framework. All the classes are fully documented. When needed, code snippets are present as well. And there are quite a lot of examples to get started.

Without going as far as Qt, it would be a nice long term goal to have Falco's libraries fully documented. This would allow to generate the API documentation which is always a nice to have when making use of a library.

There are several (complimentary) ways that this could be achieved:

• Each time someone modifies a function that is not yet documented, add it
• Each time a new API is added, mandatory document it
• Have documentation sprints where people gather to do just that: take the time to document

This does not need to be the work of a single person.

One thing that could be done in that context is the creation of a group/team of people interested in this topic. They could help plan out the work on the long term, prepare guidelines, help review submission (style is as important as accuracy), etc. This would allow to have a consistent work done through all the Falco projects.

[incertum]

Fully supportive, on top I actually see an urgent need to fully define our coding style. @Andreagit97 started an effort a while ago #470. Perhaps more folks can help, such as yourself @sgaist or @federico-sysdig and @falcosecurity/libs-maintainers?