[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?

[poiana]

Issues go stale after 90d of inactivity.

Mark the issue as fresh with /remove-lifecycle stale.

Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Provide feedback via https://github.com/falcosecurity/community.

/lifecycle stale

[incertum]

/remove-lifecycle stale

[poiana]

Issues go stale after 90d of inactivity.

Mark the issue as fresh with /remove-lifecycle stale.

Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Provide feedback via https://github.com/falcosecurity/community.

/lifecycle stale

[leogr]

/remove-lifecycle stale
/help

[poiana]

@leogr:
This request has been marked as needing help from a contributor.

Please ensure the request meets the requirements listed here.

If this request no longer meets these requirements, the label can be removed
by commenting with the /remove-help command.

In response to this:

/remove-lifecycle stale
/help

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.