TwitchLib.Api icon indicating copy to clipboard operation
TwitchLib.Api copied to clipboard

[Suggestion] Add a summary to all endpoints

Open RRickkert opened this issue 6 years ago • 1 comments

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.

RRickkert avatar Jan 22 '19 16:01 RRickkert

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 :(

swiftyspiffy avatar Feb 03 '19 23:02 swiftyspiffy