From 11043486ae1fef79ec969776bc595f9a94e09e3d Mon Sep 17 00:00:00 2001 From: Vesa Karvonen Date: Fri, 24 May 2024 10:43:18 +0300 Subject: [PATCH] Fix some typos, English idioms, and reformat the doc comments As a stylistic thing, I would recommend using an extra space after a period. Like this. And this. This makes it easier to see where sentences begin and end when using monospaced fonts and makes the text easier to read. The convention of an extra space after a period is also recognized by the `fill-paragraph` command of Emacs. --- src_lockfree/spsc_queue.mli | 74 +++++++++++++++++-------------------- 1 file changed, 34 insertions(+), 40 deletions(-) diff --git a/src_lockfree/spsc_queue.mli b/src_lockfree/spsc_queue.mli index 6450c189..c93f7bda 100644 --- a/src_lockfree/spsc_queue.mli +++ b/src_lockfree/spsc_queue.mli @@ -1,80 +1,74 @@ (** Single producer single consumer queue. *) type 'a t -(** Type of single-producer single-consumer non-resizable domain-safe - queue that works in FIFO order. *) +(** Type of single-producer single-consumer non-resizable domain-safe queue that + works in FIFO order. *) val create : size_exponent:int -> 'a t (** [create ~size_exponent:int] returns a new queue of maximum size - [2^size_exponent] and initially empty. *) + [2^size_exponent] and initially empty. *) val size : 'a t -> int -(** [size] returns the size of the queue. This method linearizes only when called - from either consumer or producer domain. Otherwise, it is safe to call but - provides only an *indication* of the size of the structure. *) +(** [size] returns the size of the queue. This method linearizes only when + called from either consumer or producer domain. Otherwise, it is safe to + call but provides only an *indication* of the size of the structure. *) (** {1 Producer functions} *) exception Full (** Raised when {!push_exn} is applied to a full queue. - This exception is meant to avoid allocations required by an option type. - As such, it does not registed backtrace information and it is recommended - to use the following pattern to catch it. + + This exception is meant to avoid allocations required by an option type. As + such, it does not register backtrace information and it is recommended to + use the following pattern to catch it. {[ match push_exn q v with - | value -> (* ... *) + | () -> (* ... *) | exception Full -> (* ... *) - ]} -*) + ]} *) val push_exn : 'a t -> 'a -> unit -(** [push q v] adds the element [v] at the end of the queue [q]. This - method can be used by at most one domain at the time. +(** [push q v] adds the element [v] at the end of the queue [q]. This method + can be used by at most one domain at a time. - @raise Full if the queue is full. -*) + @raise Full if the queue is full. *) val try_push : 'a t -> 'a -> bool -(** [try_push q v] tries to add the element [v] at the end of the - queue [q]. It fails it the queue [q] is full. This method can be - used by at most one domain at the time. -*) +(** [try_push q v] tries to add the element [v] at the end of the queue [q]. It + fails it the queue [q] is full. This method can be used by at most one + domain at a time. *) (** {2 Consumer functions} *) exception Empty (** Raised when {!pop_exn} or {!peek_exn} is applied to an empty queue. - This exception is meant to avoid allocations required by an option type. - As such, it does not registed backtrace information and it is recommended - to use the following pattern to catch it. + + This exception is meant to avoid allocations required by an option type. As + such, it does not register backtrace information and it is recommended to + use the following pattern to catch it. {[ match pop_exn q with | value -> (* ... *) | exception Empty -> (* ... *) - ]} -*) + ]} *) val pop_exn : 'a t -> 'a -(** [pop_exn q] removes and returns the first element in queue [q]. This - method can be used by at most one domain at the time. +(** [pop_exn q] removes and returns the first element in queue [q]. This method + can be used by at most one domain at a time. - @raise Empty if [q] is empty. -*) + @raise Empty if [q] is empty. *) val pop_opt : 'a t -> 'a option -(** [pop_opt q] removes and returns the first element in queue [q], or - returns [None] if the queue is empty. This method can be used by - at most one domain at the time. *) +(** [pop_opt q] removes and returns the first element in queue [q], or returns + [None] if the queue is empty. This method can be used by at most one domain + at a time. *) val peek_exn : 'a t -> 'a -(** [peek_exn q] returns the first element in queue [q]. This method can be - used by at most one domain at the time. +(** [peek_exn q] returns the first element in queue [q]. This method can be + used by at most one domain at a time. - @raise Empty if [q] is empty. -*) + @raise Empty if [q] is empty. *) val peek_opt : 'a t -> 'a option -(** [peek_opt q] returns the first element in queue [q], or [None] - if the queue is empty. This method can be used by at most one - domain at the time. -*) +(** [peek_opt q] returns the first element in queue [q], or [None] if the queue + is empty. This method can be used by at most one domain at a time. *)