Docs feedback: Events documentation does not properly specify structure of response

https://docs.gitlab.com/ee/api/events.html

The documentation here:

• Doesn't explain the purpose or format of any fields:

  • title is always null in the given examples with no explanation.

• Doesn't explain what fields will be available under what conditions:

  • target_iid exists sometimes (correction: I now realize this is because the IID is only applicable to certain targets where there is a mismatch - I suppose that's reasonable enough, but maybe this should at least be mentioned along with which target types it does exist for.)
  • target_title is sometimes null and sometimes not
  • author_username and the author object's username property both exist under some conditions, but do not appear to be identical.

• Doesn't document how the structure changes when certain Actions or Targets are being represented, or gets things wrong:

  • possible values for action_name are not documented, and are not the same as possible request action types
  • action_name is shown as "pushed" in one of the examples, but when I interact with this same API I receive "pushed to".
  • target_type is null sometimes... seems unreasonable.
  • Possible target_type values for the response are also not documented, although the request target types listed near the beginning of the documentation are similar (but downcased.)

I am making an application that displays a notification feed right now, and the lack of any real concrete specification for response data is making it incredibly difficult. I suggest that the structure of response data be made much clearer.