typing_status: Write jsdoc for main entry point, and rename.

This was named after when it gets called from the UI, rather than
after what it can be expected to do.

Naming it after what it's meant to do -- and giving a summary line to
expand on that -- provides a more helpful semantic idea for reasoning
about the function.  Doubly so for using the function in a different
client with its own UI, like the mobile app.

frontend_tests/node_tests/typing_status.js

@@ -16,7 +16,7 @@ run_test('basics', () => {
 
     // invalid conversation basically does nothing
     var worker = {};
-    typing_status.handle_text_input(worker, undefined);
+    typing_status.update(worker, undefined);
 
     // Start setting up more testing state.
     typing_status.initialize_state();
@@ -55,7 +55,7 @@ run_test('basics', () => {
 
     function call_handler(new_recipient) {
         clear_events();
-        typing_status.handle_text_input(worker, new_recipient);
+        typing_status.update(worker, new_recipient);
     }
 
     function call_stop() {
@@ -281,12 +281,12 @@ run_test('basics', () => {
 
     // User ids of poeple in compose narrow doesn't change and is same as stat.current_recipent
     // so counts of function should increase except stop_last_notification
-    typing_status.handle_text_input(worker, typing.get_recipient());
+    typing_status.update(worker, typing.get_recipient());
     assert.deepEqual(call_count.maybe_ping_server, 1);
     assert.deepEqual(call_count.start_or_extend_idle_timer, 1);
     assert.deepEqual(call_count.stop_last_notification, 0);
 
-    typing_status.handle_text_input(worker, typing.get_recipient());
+    typing_status.update(worker, typing.get_recipient());
     assert.deepEqual(call_count.maybe_ping_server, 2);
     assert.deepEqual(call_count.start_or_extend_idle_timer, 2);
     assert.deepEqual(call_count.stop_last_notification, 0);
@@ -294,7 +294,7 @@ run_test('basics', () => {
     // change in recipient and new_recipient should make us
     // call typing_status.stop_last_notification
     compose_pm_pill.get_user_ids_string = () => '2,3,4';
-    typing_status.handle_text_input(worker, typing.get_recipient());
+    typing_status.update(worker, typing.get_recipient());
     assert.deepEqual(call_count.maybe_ping_server, 2);
     assert.deepEqual(call_count.start_or_extend_idle_timer, 3);
     assert.deepEqual(call_count.stop_last_notification, 1);

static/js/typing.js

@@ -66,7 +66,7 @@ exports.initialize = function () {
         // start-typing notice immediately.
         var new_recipient =
           is_valid_conversation() ? exports.get_recipient() : undefined;
-        typing_status.handle_text_input(worker, new_recipient);
+        typing_status.update(worker, new_recipient);
     });
 
     // We send a stop-typing notification immediately when compose is

static/shared/js/typing_status.js

@@ -1,7 +1,5 @@
 import _ from "underscore";
 
-// See docs/subsystems/typing-indicators.md for details on typing indicators.
-
 // The following constants are tuned to work with
 // TYPING_STARTED_EXPIRY_PERIOD, which is what the other
 // users will use to time out our messages.  (Or us,
@@ -14,20 +12,6 @@ var TYPING_STARTED_WAIT_PERIOD = 10000; // 10s
 // do we send a 'stopped typing' notification
 var TYPING_STOPPED_WAIT_PERIOD = 5000; // 5s
 
-/*
-
-    Our parent should pass in a worker object with the following
-    callbacks:
-
-        notify_server_start
-        notify_server_stop
-        get_current_time
-
-    See typing.js for the implementations of the above. (Our
-    node tests also act as workers and will stub those functions
-    appropriately.)
-*/
-
 /** Exported only for tests. */
 export const state = {};
 
@@ -85,7 +69,33 @@ export function maybe_ping_server(worker, recipient) {
     }
 }
 
-export function handle_text_input(worker, new_recipient) {
+/**
+ * Update our state machine, and the server as needed, on the user's typing status.
+ *
+ * This can and should be called frequently, on each keystroke.  The
+ * implementation sends "still typing" notices at an appropriate throttled
+ * rate, and keeps a timer to send a "stopped typing" notice when the user
+ * hasn't typed for a few seconds.
+ *
+ * Zulip supports typing notifications only for PMs (both 1:1 and group); so
+ * composing a stream message should be treated like composing no message at
+ * all.
+ *
+ * Call with `new_recipient` of `undefined` when the user actively stops
+ * composing a message.  If the user switches from one set of recipients to
+ * another, there's no need to call with `undefined` in between; the
+ * implementation tracks the change and behaves appropriately.
+ *
+ * See docs/subsystems/typing-indicators.md for detailed background on the
+ * typing indicators system.
+ *
+ * @param {*} worker Callbacks for reaching the real world.  See typing.js
+ *   for implementations.
+ * @param {*} new_recipient The users the PM being composed is addressed to,
+ *   as a sorted array of user IDs; or `undefined` if no PM is being
+ *   composed anymore.
+ */
+export function update(worker, new_recipient) {
     var current_recipient = state.current_recipient;
     if (current_recipient) {
         // We need to use _.isEqual for comparisons; === doesn't work

static/shared/js/typing_status.js.flow

@@ -12,7 +12,7 @@ type Worker = {|
   notify_server_stop: RecipientUserIds => void
 |};
 
-declare export function handle_text_input(
+declare export function update(
   worker: Worker,
   new_recipient: RecipientUserIds | void,
 ): void;