More meaningful specs for the backing queue, and removal of duplicated and potentially divergent documentation with the specs

2 files changed, 17 insertions, 15 deletions

diff --git a/include/rabbit_backing_queue_spec.hrl b/include/rabbit_backing_queue_spec.hrl
index 7c83bb5213..0a0931ea34 100644
--- a/include/rabbit_backing_queue_spec.hrl
+++ b/include/rabbit_backing_queue_spec.hrl
@@ -32,16 +32,20 @@
 -type(fetch_result() ::
                  %% Message,  IsDelivered,  AckTag,  Remaining_Len
         ('empty'|{basic_message(), boolean(), ack(), non_neg_integer()})).
+-type(is_durable() :: boolean()).
+-type(attempt_recovery() :: boolean()).
+-type(purged_msg_count() :: non_neg_integer()).
+-type(ack_required() :: boolean()).
 
 -spec(start/1 :: ([queue_name()]) -> 'ok').
--spec(init/3 :: (queue_name(), boolean(), boolean()) -> state()).
+-spec(init/3 :: (queue_name(), is_durable(), attempt_recovery()) -> state()).
 -spec(terminate/1 :: (state()) -> state()).
 -spec(delete_and_terminate/1 :: (state()) -> state()).
--spec(purge/1 :: (state()) -> {non_neg_integer(), state()}).
+-spec(purge/1 :: (state()) -> {purged_msg_count(), state()}).
 -spec(publish/2 :: (basic_message(), state()) -> state()).
 -spec(publish_delivered/3 ::
-        (boolean(), basic_message(), state()) -> {ack(), state()}).
--spec(fetch/2 :: (boolean(), state()) -> {fetch_result(), state()}).
+        (ack_required(), basic_message(), state()) -> {ack(), state()}).
+-spec(fetch/2 :: (ack_required(), state()) -> {fetch_result(), state()}).
 -spec(ack/2 :: ([ack()], state()) -> state()).
 -spec(tx_publish/3 :: (txn(), basic_message(), state()) -> state()).
 -spec(tx_ack/3 :: (txn(), [ack()], state()) -> state()).
diff --git a/src/rabbit_backing_queue.erl b/src/rabbit_backing_queue.erl
index f21c290f05..38bee4663b 100644
--- a/src/rabbit_backing_queue.erl
+++ b/src/rabbit_backing_queue.erl
@@ -42,12 +42,10 @@ behaviour_info(callbacks) ->
      %% shared resources.
      {start, 1},
 
-     %% Called with queue name, a boolean to indicate whether or
-     %% not the queue is durable, and a boolean to indicate whether
-     %% the queue contents should be attempted to be recovered.
+     %% Initialise the backing queue and its state.
      {init, 3},
 
-     %% Called on queue shutdown when queue isn't being deleted
+     %% Called on queue shutdown when queue isn't being deleted.
      {terminate, 1},
 
      %% Called when the queue is terminating and needs to delete all
@@ -58,7 +56,7 @@ behaviour_info(callbacks) ->
      %% been fetched and are pending acks.
      {purge, 1},
 
-     %% Publish a message
+     %% Publish a message.
      {publish, 2},
 
      %% Called for messages which have already been passed straight
@@ -66,11 +64,11 @@ behaviour_info(callbacks) ->
      %% (i.e. saves the round trip through the backing queue).
      {publish_delivered, 3},
 
-     %% Produce the next message
+     %% Produce the next message.
      {fetch, 2},
 
      %% Acktags supplied are for messages which can now be forgotten
-     %% about
+     %% about.
      {ack, 2},
 
      %% A publish, but in the context of a transaction.
@@ -118,12 +116,12 @@ behaviour_info(callbacks) ->
      {ram_duration, 1},
 
      %% Can return 'undefined' or a thunk which will receive the
-     %% state, and must return the state, as soon as the queue process
-     %% can manage (either on an empty mailbox, or when a timer
-     %% fires).
+     %% state, and must return the state, which will be invoked as
+     %% soon as the queue process can manage (either on an empty
+     %% mailbox, or when a timer fires).
      {sync_callback, 1},
 
-     %% Called immediately before the queue hibernates
+     %% Called immediately before the queue hibernates.
      {handle_pre_hibernate, 1},
 
      %% Exists for debugging purposes, to be able to expose state via