Open sgaist opened 6 months ago
incertum
commented
6 months ago Fully supportive, on top I actually see an urgent need to fully define our coding style. @Andreagit97 started an effort a while ago https://github.com/falcosecurity/libs/pull/470. Perhaps more folks can help, such as yourself @sgaist or @federico-sysdig and @falcosecurity/libs-maintainers?
poiana
commented
3 months ago 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
commented
3 months ago /remove-lifecycle stale
poiana
commented
1 week ago 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
commented
1 week ago /remove-lifecycle stale /help
poiana
commented
1 week ago @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.
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:
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.