I will be leaving my current project in a few days, and as part of securing my knowledge I have been asked to add comments to the code wherever I feel that can add value.
The problem I am running into now is that the comments I want to write are not really suitable as comments, because they do not pertain to a single entity in the code (a few lines, a function, a class or even a file), but they are more about how two or more entities interact with each other or about a feature whose implementation is spread over multiple entities.
So, how do you go about documenting the stuff that does not belong to a single entity but is important to know to understand the bigger picture?
And also: Where do you document it? In the source file or in an external document?
As an example, we have a client-server architecture in C (with the client and server both running on the same embedded device). To avoid flooding the server, the client has a mechanism to throttle the sending of similar requests to the server such that a request can only be sent if the previous one has been answered.
The innards of this mechanism are spread over multiple functions.
Where would you place the documentation of such a feature, especially if the file with the functionality also has some other, unrelated, functions?
Edit: Extended the question a bit.