Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Suggestion] Add a summary to all endpoints #106

Open
RRickkert opened this issue Jan 22, 2019 · 1 comment
Open

[Suggestion] Add a summary to all endpoints #106

RRickkert opened this issue Jan 22, 2019 · 1 comment

Comments

@RRickkert
Copy link
Member

Sometimes it can be quite unclear what an endpoint in the API does exactly.
Along with that, it can throw unexpected exceptions which aren't documented anywhere.
Next to that, even the parameter names aren't quite clear from time to time.

So my suggestion is to start adding summaries to at least all future added endpoints (Helix) and try to add a summary to all current Helix endpoints which are already created.
For V5 endpoints, it would be nice, but since it's a bit depreciated and it should be removed at the end of the year), it might not be worth adding them to those endpoints.

An example of a summary would be:

/// <summary>
/// <see href="https://dev.twitch.tv/docs/api/reference/#replace-stream-tags">Replace Stream Tags</see>
/// </summary>
/// <exception cref="ArgumentNullException">When the <paramref name="broadcasterId"/> is null.</exception>
/// <exception cref="ArgumentException">When the amount of tags in <paramref name="tagIds"/> is more than 5.</exception>
/// <param name="broadcasterId">ID of the stream for which tags are to be replaced.</param>
/// <param name="tagIds">IDs of tags to be applied to the stream.</param>
/// <param name="accessToken">An accessToken to use for this specific request.</param>

Preferably it would also have the methods which can be thrown internally, such as BadScopeException, BadGatewayException, InternalServerErrorException, etc. Since it's possible that this method throws those errors and a user should know that he/she needs to handle them if such a thing happens for whatever reason.

@swiftyspiffy
Copy link
Member

This is a good suggestion, just seems like it'll take a ton of time, something I don't have much of at the moment :(

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants