Document the aws jslib's EventBridge support #1348
Conversation
|
There's a version of the docs published here: https://mdr-ci.staging.k6.io/docs/refs/pull/1348/merge It will be deleted automatically in 30 days. |
src/data/markdown/docs/20 jslib/01 jslib/01 aws/00 EventBridge.md
Outdated
Show resolved
Hide resolved
|
|
||
| | Parameter | Type | Description | | ||
| | :------------ | :-------------- | :----------------------------------------------------------------------------------------------------------------------- | | ||
| | input | [PutEventsInput](#puteventsinput) | An array of objects representing events to be submitted. | |
There was a problem hiding this comment.
I'm looking at both input and Entries with the same description, and I'm wondering if this would be more accurate if it said: "An object with the key Entries and the value of an array of EventBridgeEntry, representing events to be submitted.", or something along these lines.
Wdyt? Or is this more confusing?
There was a problem hiding this comment.
I see what you mean, but the PutEventsInput is a data interface defined by AWS, which we also define in the code, and which also has other attributes such as EndpointId (and I believe more that we haven't included yet).
Thus, I believe it is better kept this way.
However, I'm not happy with how we deal with these nested type definitions in the docs at the moment. The problem is that if the argument to a function is an object with a strict form and shape that we expect, it's hard to describe it to the user in a concise way. Having multiple tables, as I did here, was my best bet. We could also have dedicated separate pages, but that makes documenting a library like AWS very cumbersome.
What do you think? Maybe you see an alternative that would be more friendly to both the user and the documentation writer? 😄 🙇🏻
There was a problem hiding this comment.
That's a great point... And I think tables are an ok solution for right now, feel free to merge this PR.
I'll open a separate issue so we can discuss/test some different ways of how to better display nested objects, maybe we can look at some other docs and get some ideas. :)
There was a problem hiding this comment.
Please do so, I'm really keen to work on this with you and think about how we might improve it in the future indeed 👍🏻
Co-authored-by: Heitor Tashiro Sergent <heitortsergent@gmail.com>
This Pull Request documents the newly introduced support for the AWS EventBridge service.