Document the data model for user presence

[gnprice]

We have some docs on the user-presence subsystem, here:
https://zulip.readthedocs.io/en/latest/subsystems/presence.html

They're helpful, but there are some important areas they don't cover, or don't make clear. These have caused confusion a few times in the mobile app. Here are some that recently came up:

• The relationship between the three states active, idle, offline. (And/or inactive? We were using that name in some recent discussions, but I don't now see it in the code. Another reason it'd be good if the exact set of states were documented. 😉 )
• In particular, inactive is reached by aging from either active or idle.
• The relationship between those states, and the presence information the client reports to the server.
• One extra-confusing point when not clearly documented: reporting idle doesn't mean "I'm going away now, goodbye". It means "Here I am! Still here! BTW the user hasn't interacted with me for a while."
• How a client should behave in reporting presence.
  • Notably: it shouldn't try to send an idle report in reaction to being closed or backgrounded.

For recent discussion figuring out what things meant, see this chat thread; discussion at zulip/zulip-mobile#3699; and discussion at zulip/zulip-mobile#3704.

For much of this information, the ideal place is really in and right next to code. Some bits of it are in comments on the UserPresence model, and a link to there would be good. For some others, a good comment in an appropriate place, and a link here to that comment, could be a good format. But one way or another we should write it down.

Here are points that I don't think came up in the past couple of weeks, but have in the past and would be good to clarify:

• The relationship between presence and user status / away-status.
• Just how a client should aggregate, and interpret for the UI, the presence data it has on other users. (This is perhaps an especially good target for a good block comment in the relevant code in the web frontend, and a link there from here.) The mobile app has getAggregatedPresence and related functions, and after a couple of rounds (at different times a while ago) of staring at the subsystem docs and at the web implementation and revising this logic, I'm still not particularly confident that they are quite right.

[zulipbot]

Hello @zulip/server-api, @zulip/server-development, @zulip/server-sidebars members, this issue was labeled with the "area: documentation (api and integrations)", "area: documentation (developer)", "area: right-sidebar" labels, so you may want to check it out!

[gnprice]

This remains underdocumented. I believe the current plan is to eventually rewrite this area of the API, rather than document it.

See the recently-merged #16381 / #15030, which was originally said to implement a design described at #13734 (comment) (but that was long before the eventual merge, and I haven't tried to determine to what extent the design changed).

For more recent discussion of the future design, see chat here: https://chat.zulip.org/#narrow/stream/378-api-design/topic/presence.20rewrite/near/1513812 .

Also in that thread, @timabbott described the work leading to #16381 like so:

Ultimately our goal is to be able to discard this old system in part because it was hard to understand, inefficient, and not fun to document; this change is just the transitional work to make it possible to offer a simpler API without the server having to do something very inefficient to coerce a sane API into these data structures.

(If we were going to document this data model, one change since 2019 is that we now have documentation for the Zulip API in general. So whereas above in 2019 I said:

For much of this information, the ideal place is really in and right next to code.

the ideal place today would be in the API documentation, and in particular at or linked to from https://zulip.com/api/get-events#presence and https://zulip.com/api/get-presence . Then comments in the server code would link to there.)