Update Event interface code doc

[chrisdoherty4]

The Event interface is implemented by all events. The code docs were not clear on how a consumer leverages the Event interface to handle the event (for example transport the event).

This code doc clarifies the intended usage of the Event interface.

[codecov]

Codecov Report

Merging #825 (80fd36f) into main (fb0c11c) will not change coverage.
Report is 3 commits behind head on main.
The diff coverage is n/a.

❗ Current head 80fd36f differs from pull request most recent head 946b93c. Consider uploading reports for the commit 946b93c to get more accurate results

@@           Coverage Diff           @@
##             main     #825   +/-   ##
=======================================
  Coverage   51.16%   51.16%           
=======================================
  Files          33       33           
  Lines        1456     1456           
=======================================
  Hits          745      745           
  Misses        665      665           
  Partials       46       46           

📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more

[jacobweinstock]

This is great, thanks. A few suggestions for things to add that I think would be helpful for implementors.

• what "recordable event" is, means, and when/where events are recorded (i believe its just in the agent logic).
• transports implementations are responsible for sending the event.
• concrete event types will contain more context that can be used when sending an event.

[chrisdoherty4]

I can add something for the first 2. Isn't the third point covered by the comment on how to use and the example?

[chrisdoherty4]

I've tweaked this a little but I decided not to make any mention of transport because thats 1 of possibly more consumers. I think the documentation in this package needs to be tight and relevant to the package itself.

We could add documentation elsewhere that strings everything together but I don't think its appropriate for this interface.