Confusion over what Presences are returned by the Ready Event

[flaw600]

My apologies if this question has already been answered and/or documented. I was looking through the docs and noticed that on a Ready event, an array of Presences for the user's friends (not applicable to bots) would be returned. Is that array supposed to contain the Presences for all of the user's friends or just some subset of them? I ask because currently for my app, only a small subset of Presences are being returned so I wanted to know what I should be expecting. Thank you for your attention.

[jhgg]

This field is only for user accounts and thus doesn't fall under the scope of this API documentation - nor are we offering support for it.

[flaw600]

@jhgg then why put it in the documentation at all? This API documentation does actually document the user friend Presences in the Ready event, so I'm unclear why the question isn't in-scope. To be clear, the reason that I figured that it would be in-scope is because the API documentation does document the field and we're told to visit this GH repo to submit PR's and ask questions. I'm not asking for support for my app, merely asking what I should be expecting

[jhgg]

Looks like those are there erroneously - I'll remove them - as the fields aren't relevant to bot accounts - and thus are irrelevant from this documentation (as we're not documenting the API from a user client perspective).

However, to answer your question though, presences omit offline friends.

[flaw600]

@jhgg There are a number of fields that are user only that are documented (in addition to the ones that you removed in the latest commit), so is it possible to keep them and just put a note that questions about them won't be answered, for the sake of consistency? The documentation already has notices for conditions that you want to put on for various other fields on information, so it shouldn't be too hard to do it for this type of field. That way you aren't responsible for answering questions about them, but library and bot devs can get at least get the unofficial explanation coverage that they are getting already (for self-bots, admittedly, but those are tolerated if coded correctly, to my understanding). I feel like that would be a fair compromise. I don't want to be responsible for library devs having to consider whether to support the rewrite, and bot developers having to possibly re-write their code, and keeping the fields in the documentation would remove the possibility of confusion between the docs that libraries provide and this one. If you didn't want to go through the documentation and put those warnings in, I'd be willing to do it as I feel like consistency and avoiding needless confusion could be done here.

[jhgg]

Indeed - the documentation does have its flaws. To avoid confusion, we want to write the documentation from the perspective of a bot only - libraries and authors looking to integrate with Discord shouldn't have to worry about user only fields/API endpoints - as we reserve the right to break and change them as we see fit (which makes them a very volatile target to develop against as a 3rd party author).

When we have more bandwidth - we'd like to make those changes - but we've definitely been heading in that direction (e.g. #202). If you have the time - those are the kinds of changes we'd appreciate - in addition to cleaning up the rough edges. We have no interest in documenting all the user only APIs - as I said - they serve no use outside of our client and we do change/break them as we see fit. Keeping them publically documented only adds additional development burden for little to no practical gain.

[flaw600]

@jhgg My point wasn't to highlight the documentation's "flaws," (my point was that I don't consider them as flaws) but to merely point out that for sake of consistency, it is better to leave the documentation as-is. I'm not suggesting that you don't have the right to break or change the endpoints as you wish, nor am I suggesting that you don't in the future. My point is that you've established the practice of trying to keep the documentation current and accurate to the current state of the API, with the exception of sometimes updating documentation before the rollout of API changes, and I'm asking you to keep that practice in this instance.

While I can understand your desire to write the documentation from the perspective of a true bot, removing documentation for the implementation of self-bots - something that has been suggested is tolerated/accepted although not well-liked by multiple people - really only sows confusion, especially when the edited documentation is technically inaccurate. You could achieve the goal of not confusing developers by putting a warning next to especially volatile targets (like say, endpoints that are user-only). As you've seen by the response to sudden API changes in the past (including the issue that is still open), developers are generally quick to react - they will change to conform to the technical specifications to the API. But I do think that it's unfair to say that developers would get confused by documentation for endpoints that explicitly say that the respective endpoint is user-only. For example, I was not confused about the <Client>.presences field - I was well aware that it was a user-field, but wanted clarification on what it returned because the documentation wasn't clear. That wasn't a bot/user failing, that was simply me not understanding the language used - the same confusion would've occurred if it were a bot field. If the user-only endpoints break, developers will be prepared for them breaking. But they haven't broken yet, hence my request that you restore the content that you removed. My point is this: to my understanding, selfbots are tolerated and thus far the methods to implement them have been documented, and the documentation is current; removing said documentation while still being able to implement them sows confusion which is what you want to avoid. For these reasons, I implore you to please restore the documentation that you deleted. If the user-only endpoints change and the documentation does not, well as you pointed out you don't really officially support user-only endpoints anyway. But until and unless that happens, it really does you no harm to keep the documentation as-is and tell people like me who ask questions about those endpoints that those aren't officially supported - remember that I was confused about why the question wasn't API in-scope but never contested that the endpoints weren't officially supported (honestly, I didn't know about the Discord API Server, otherwise I would've asked my question there instead of here - the better solution imo would've been to tell me to go there rather than remove references to endpoints that do actually still exist).

(P.S. would you mind moving this conversation to a Discord DM? GH issue pages are really not suited to maintaining such discussions imho.)

(P.S.S. I apologize for the tagging, but I'm not sure how GH notifications work for closed issues. )