[tracking] Improve code documentation

[sgaist]

This ticket is a follow up of today's community meeting (and heavily inspired from falcosecurity/libs#1747.

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

The longer story: while the falco 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.

While the application itself is not a library to be used by others, the people wanting to work on the code would benefit from having it better documented. This helps working on bug fixes and features without requiring to read through all the implementation to understand how things are used.

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, see also my comment in the libs equivalent ticket falcosecurity/libs#1747 (comment).

[sgaist]

As an example of something that should be part of the contributor documentation: https://falco.org/blog/intro-development-falco/
The simple trick for using a local checkout of falcosecurity/libs is very handy when one wants to prepare a new feature for falco based on unreleased changes in libs and I think should be part of a "Getting started to hack on Falco" document which is different from "Building Falco from sources".