chore(docs): replace IN and OUT macros with docs

[Molter73]

What type of PR is this?

/kind cleanup

/kind documentation

Any specific area of the project related to this PR?

/area libscap-engine-bpf

/area libscap-engine-kmod

/area libscap-engine-modern-bpf

/area libscap-engine-source-plugin

/area libscap

/area libsinsp

/area tests

Does this PR require a change in the driver versions?

What this PR does / why we need it:

In scap.h, we have a couple of quite generic macros called IN and OUT that can very easily leak into adopter's code bases and wreak havoc (i.e: we actually had these macros override parameters in an auto-generated enum from protobufs that were literally called IN and OUT, giving very confusing compilation errors).

From my understanding, these macros are only used for documenting which parameters in a function are input and which are output. Since they are not consistently used, only appear in a handful of places in the codebase and the preprocessor is the devil's spawn, we should replace these macros with proper doxygen style string docs.

Alternatively, we could rename them to something like SCAP_IN and SCAP_OUT, so collision with adopters code would be harder, but I think removing them is the more sensible approach.

Which issue(s) this PR fixes:

Fixes #

Special notes for your reviewer:

This PR touches a bunch of different places in the code base, but it should only be removing the IN and OUT macros that normally expands to empty strings, so there should be no effective changes to code.

The added doc descriptions might not be specific enough, so any comments on how to improve them are more than welcomed.

Does this PR introduce a user-facing change?:

NONE

[github-actions[bot]]

Please double check driver/API_VERSION file. See versioning.

/hold

[leogr]

Please double check driver/API_VERSION file. See versioning.

/hold

Hey @Molter73

I believe this is a false positive. If I understood correctly, your PR is a no-op from the kernelspace<->userspace APIs backward compatibility perspective. Right?

[leogr]

cc @falcosecurity/libs-maintainers for visibility /milestone 0.17.0

[Molter73]

Please double check driver/API_VERSION file. See versioning. /hold

Hey @Molter73

I believe this is a false positive. If I understood correctly, your PR is a no-op from the kernelspace<->userspace APIs backward compatibility perspective. Right?

Yup, no actual code change should happen since the removed macros expand to empty strings anyways.

[leogr]

Please double check driver/API_VERSION file. See versioning. /hold

Hey @Molter73 I believe this is a false positive. If I understood correctly, your PR is a no-op from the kernelspace<->userspace APIs backward compatibility perspective. Right?

Yup, no actual code change should happen since the removed macros expand to empty strings anyways.

:+1: /unhold

[incertum]

I don't have any problems with these changes @leogr - let's wait to hear from the others.

[leogr]

it's good for me too. @Molter73 could you rebase pls? :pray:

[poiana]

LGTM label has been added.

Git tree hash: d01e0bf03fdbf9095cb8ef7f5efe03b06be67475

[poiana]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: incertum, leogr, Molter73

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• ~~OWNERS~~ [Molter73,incertum,leogr]

Approvers can indicate their approval by writing /approve in a comment Approvers can cancel approval by writing /approve cancel in a comment