Reformat long comments before clang-format
Test: mma -j32
Change-Id: I86a2a4af9dcd22d675ca1f764bb2c9623d63edcc
diff --git a/osi/include/array.h b/osi/include/array.h
index fa05d87..ecbb1bc 100644
--- a/osi/include/array.h
+++ b/osi/include/array.h
@@ -29,10 +29,8 @@
typedef struct array_t array_t;
// Returns a new array object that stores elements of size |element_size|. The
-// returned
-// object must be freed with |array_free|. |element_size| must be greater than
-// 0. Returns
-// NULL on failure.
+// returned object must be freed with |array_free|. |element_size| must be
+// greater than 0. Returns NULL on failure.
array_t* array_new(size_t element_size);
// Frees an array that was allocated with |array_new|. |array| may be NULL.
@@ -43,8 +41,7 @@
void* array_ptr(const array_t* array);
// Returns a pointer to the |index|th element of |array|. |index| must be less
-// than
-// the array's length. |array| must not be NULL.
+// than the array's length. |array| must not be NULL.
void* array_at(const array_t* array, size_t index);
// Returns the number of elements stored in |array|. |array| must not be NULL.
@@ -60,10 +57,8 @@
// Inserts an element to the end of |array|. The value pointed to by |data| must
// be at least |element_size| bytes long and will be copied into the array.
-// Neither
-// |array| nor |data| may be NULL. Returns true if the element could be inserted
-// into
-// the array, false on error.
+// Neither |array| nor |data| may be NULL. Returns true if the element could be
+// inserted into the array, false on error.
bool array_append_ptr(array_t* array, void* data);
#ifdef __cplusplus
diff --git a/osi/include/buffer.h b/osi/include/buffer.h
index 211f0d6..6589c70 100644
--- a/osi/include/buffer.h
+++ b/osi/include/buffer.h
@@ -36,8 +36,7 @@
// from the original: writes to the original will be reflected in the reference
// and vice versa. In other words, this function creates an alias to |buf|. The
// caller must release the returned buffer with |buffer_free|. Note that
-// releasing
-// the returned buffer does not release |buf|. |buf| must not be NULL.
+// releasing the returned buffer does not release |buf|. |buf| must not be NULL.
buffer_t* buffer_new_ref(const buffer_t* buf);
// Creates a new reference to the last |slice_size| bytes of |buf|. See
diff --git a/osi/include/config.h b/osi/include/config.h
index 2243c27..1480151 100644
--- a/osi/include/config.h
+++ b/osi/include/config.h
@@ -123,19 +123,14 @@
// The returned pointer must be treated as an opaque handle and must not be
// freed.
// The iterator is invalidated on any config mutating operation. |config| may
-// not
-// be NULL.
+// not be NULL.
const config_section_node_t* config_section_begin(const config_t* config);
// Returns an iterator to one past the last section in the config file. It does
-// not
-// represent a valid section, but can be used to determine if all sections have
-// been
-// iterated over. The returned pointer must be treated as an opaque handle and
-// must
-// not be freed and must not be iterated on (must not call |config_section_next|
-// on
-// it). |config| may not be NULL.
+// not represent a valid section, but can be used to determine if all sections
+// have been iterated over. The returned pointer must be treated as an opaque
+// handle and must not be freed and must not be iterated on (must not call
+// |config_section_next| on it). |config| may not be NULL.
const config_section_node_t* config_section_end(const config_t* config);
// Moves |iter| to the next section. If there are no more sections, |iter| will
@@ -145,24 +140,17 @@
const config_section_node_t* iter);
// Returns the name of the section referred to by |iter|. The returned pointer
-// is
-// owned by the config module and must not be freed by the caller. The pointer
-// will
-// remain valid until |config_free| is called. |iter| may not be NULL and must
-// not
-// equal the value returned by |config_section_end|.
+// is owned by the config module and must not be freed by the caller. The
+// pointer will remain valid until |config_free| is called. |iter| may not be
+// NULL and must not equal the value returned by |config_section_end|.
const char* config_section_name(const config_section_node_t* iter);
// Saves |config| to a file given by |filename|. Note that this could be a
-// destructive
-// operation: if |filename| already exists, it will be overwritten. The config
-// module does not preserve comments or formatting so if a config file was
-// opened
-// with |config_new| and subsequently overwritten with |config_save|, all
-// comments
-// and special formatting in the original file will be lost. Neither |config|
-// nor
-// |filename| may be NULL.
+// destructive operation: if |filename| already exists, it will be overwritten.
+// The config module does not preserve comments or formatting so if a config
+// file was opened with |config_new| and subsequently overwritten with
+// |config_save|, all comments and special formatting in the original file will
+// be lost. Neither |config| nor |filename| may be NULL.
bool config_save(const config_t* config, const char* filename);
#ifdef __cplusplus
diff --git a/osi/include/eager_reader.h b/osi/include/eager_reader.h
index ad4887b..6b8b25f 100644
--- a/osi/include/eager_reader.h
+++ b/osi/include/eager_reader.h
@@ -37,10 +37,9 @@
// Creates a new eager reader object, which pulls data from |fd_to_read| into
// buffers of size |buffer_size| allocated using |allocator|, and has an
// internal read thread named |thread_name|. The returned object must be freed
-// using
-// |eager_reader_free|. |fd_to_read| must be valid, |buffer_size| and
-// |max_buffer_count|
-// must be greater than zero. |allocator| and |thread_name| may not be NULL.
+// using |eager_reader_free|. |fd_to_read| must be valid, |buffer_size| and
+// |max_buffer_count| must be greater than zero. |allocator| and |thread_name|
+// may not be NULL.
eager_reader_t* eager_reader_new(int fd_to_read, const allocator_t* allocator,
size_t buffer_size, size_t max_buffer_count,
const char* thread_name);
@@ -58,8 +57,7 @@
eager_reader_cb read_cb, void* context);
// Unregisters |reader| from whichever reactor it is registered with, if any.
-// This
-// function is idempotent.
+// This function is idempotent.
void eager_reader_unregister(eager_reader_t* reader);
// Reads up to |max_size| bytes into |buffer| from currently available bytes.
diff --git a/osi/include/fixed_queue.h b/osi/include/fixed_queue.h
index c067e63..dd8a273 100644
--- a/osi/include/fixed_queue.h
+++ b/osi/include/fixed_queue.h
@@ -126,12 +126,9 @@
int fixed_queue_get_dequeue_fd(const fixed_queue_t* queue);
// Registers |queue| with |reactor| for dequeue operations. When there is an
-// element
-// in the queue, ready_cb will be called. The |context| parameter is passed,
-// untouched,
-// to the callback routine. Neither |queue|, nor |reactor|, nor |read_cb| may be
-// NULL.
-// |context| may be NULL.
+// element in the queue, ready_cb will be called. The |context| parameter is
+// passed, untouched, to the callback routine. Neither |queue|, nor |reactor|,
+// nor |read_cb| may be NULL. |context| may be NULL.
void fixed_queue_register_dequeue(fixed_queue_t* queue, reactor_t* reactor,
fixed_queue_cb ready_cb, void* context);
diff --git a/osi/include/list.h b/osi/include/list.h
index 1ecded9..e38977b 100644
--- a/osi/include/list.h
+++ b/osi/include/list.h
@@ -40,15 +40,11 @@
typedef bool (*list_iter_cb)(void* data, void* context);
// Returns a new, empty list. Returns NULL if not enough memory could be
-// allocated
-// for the list structure. The returned list must be freed with |list_free|. The
-// |callback| specifies a function to be called whenever a list element is
-// removed
-// from the list. It can be used to release resources held by the list element,
-// e.g.
-// memory or file descriptor. |callback| may be NULL if no cleanup is necessary
-// on
-// element removal.
+// allocated for the list structure. The returned list must be freed with
+// |list_free|. The |callback| specifies a function to be called whenever a
+// list element is removed from the list. It can be used to release resources
+// held by the list element, e.g. memory or file descriptor. |callback| may
+// be NULL if no cleanup is necessary on element removal.
list_t* list_new(list_free_cb callback);
// Frees the list. This function accepts NULL as an argument, in which case it
@@ -103,12 +99,9 @@
// Removes |data| from the list. Neither |list| nor |data| may be NULL. If
// |data|
// is inserted multiple times in the list, this function will only remove the
-// first
-// instance. If a free function was specified in |list_new|, it will be called
-// back
-// with |data|. This function returns true if |data| was found in the list and
-// removed,
-// false otherwise.
+// first instance. If a free function was specified in |list_new|, it will be
+// called back with |data|. This function returns true if |data| was found in
+// the list and removed, false otherwise.
bool list_remove(list_t* list, void* data);
// Removes all elements in the list. Calling this function will return the list
@@ -117,25 +110,20 @@
void list_clear(list_t* list);
// Iterates through the |list| and calls |callback| for each data element.
-// Iteration
-// continues until |callback| returns false. The function returns the pointer to
-// last
-// processed element, or NULL if the list is empty, or all calls to |callback|
-// returned
-// true. |context| is passed to |callback| on each iteration.
+// Iteration continues until |callback| returns false. The function returns the
+// pointer to last processed element, or NULL if the list is empty, or all calls
+// to |callback| returned true. |context| is passed to |callback| on each
+// iteration.
// If the list is empty, |callback| will never be called. It is safe to mutate
-// the
-// list inside the callback. If an element is added before the node being
-// visited,
-// there will be no callback for the newly-inserted node. Neither |list| nor
-// |callback| may be NULL.
+// the list inside the callback. If an element is added before the node being
+// visited, there will be no callback for the newly-inserted node. Neither
+// |list| nor |callback| may be NULL.
list_node_t* list_foreach(const list_t* list, list_iter_cb callback,
void* context);
// Returns an iterator to the first element in |list|. |list| may not be NULL.
// The returned iterator is valid as long as it does not equal the value
-// returned
-// by |list_end|.
+// returned by |list_end|.
list_node_t* list_begin(const list_t* list);
// Returns an iterator that points past the end of the list. In other words,
diff --git a/osi/include/reactor.h b/osi/include/reactor.h
index d3eca37..28af1f4 100644
--- a/osi/include/reactor.h
+++ b/osi/include/reactor.h
@@ -49,13 +49,11 @@
void reactor_free(reactor_t* reactor);
// Starts the reactor. This function blocks the caller until |reactor_stop| is
-// called
-// from another thread or in a callback. |reactor| may not be NULL.
+// called from another thread or in a callback. |reactor| may not be NULL.
reactor_status_t reactor_start(reactor_t* reactor);
// Runs one iteration of the reactor. This function blocks until at least one
-// registered object
-// becomes ready. |reactor| may not be NULL.
+// registered object becomes ready. |reactor| may not be NULL.
reactor_status_t reactor_run_once(reactor_t* reactor);
// Immediately unblocks the reactor. This function is safe to call from any
@@ -64,42 +62,32 @@
void reactor_stop(reactor_t* reactor);
// Registers a file descriptor with the reactor. The file descriptor, |fd|, must
-// be valid
-// when this function is called and its ownership is not transferred to the
-// reactor. The
-// |context| variable is a user-defined opaque handle that is passed back to the
-// |read_ready|
-// and |write_ready| functions. It is not copied or even dereferenced by the
-// reactor so it
-// may contain any value including NULL. The |read_ready| and |write_ready|
-// arguments are
-// optional and may be NULL. This function returns an opaque object that
-// represents the
-// file descriptor's registration with the reactor. When the caller is no longer
-// interested
-// in events on the |fd|, it must free the returned object by calling
+// be valid when this function is called and its ownership is not transferred
+// to the reactor. The |context| variable is a user-defined opaque handle that
+// is passed back to the |read_ready| and |write_ready| functions. It is not
+// copied or even dereferenced by the reactor so it may contain any value
+// including NULL. The |read_ready| and |write_ready| arguments are optional and
+// may be NULL. This function returns an opaque object that represents the file
+// descriptor's registration with the reactor. When the caller is no longer
+// interested in events on the |fd|, it must free the returned object by calling
// |reactor_unregister|.
reactor_object_t* reactor_register(reactor_t* reactor, int fd, void* context,
void (*read_ready)(void* context),
void (*write_ready)(void* context));
// Changes the subscription mode for the file descriptor represented by
-// |object|. If the
-// caller has already registered a file descriptor with a reactor, has a valid
-// |object|,
-// and decides to change the |read_ready| and/or |write_ready| callback
-// routines, they
-// can call this routine. Returns true if the subscription was changed, false
-// otherwise.
+// |object|. If the caller has already registered a file descriptor with a
+// reactor, has a valid |object|, and decides to change the |read_ready| and/or
+// |write_ready| callback routines, they can call this routine. Returns true if
+// the subscription was changed, false otherwise.
// |object| may not be NULL, |read_ready| and |write_ready| may be NULL.
bool reactor_change_registration(reactor_object_t* object,
void (*read_ready)(void* context),
void (*write_ready)(void* context));
// Unregisters a previously registered file descriptor with its reactor. |obj|
-// may not be NULL.
-// |obj| is invalid after calling this function so the caller must drop all
-// references to it.
+// may not be NULL. |obj| is invalid after calling this function so the caller
+// must drop all references to it.
void reactor_unregister(reactor_object_t* obj);
#ifdef __cplusplus
diff --git a/osi/include/semaphore.h b/osi/include/semaphore.h
index 29d03fd..a3d47ad 100644
--- a/osi/include/semaphore.h
+++ b/osi/include/semaphore.h
@@ -42,8 +42,7 @@
// Tries to decrement the value of |semaphore|. Returns true if the value was
// decremented, false if the value was 0. This function never blocks.
-// |semaphore|
-// may not be NULL.
+// |semaphore| may not be NULL.
bool semaphore_try_wait(semaphore_t* semaphore);
// Increments the value of |semaphore|. |semaphore| may not be NULL.
diff --git a/osi/include/socket.h b/osi/include/socket.h
index e5d4c8e..5b360b9 100644
--- a/osi/include/socket.h
+++ b/osi/include/socket.h
@@ -34,22 +34,19 @@
typedef void (*socket_cb)(socket_t* socket, void* context);
// Returns a new socket object. The socket is in an idle, disconnected state
-// when
-// it is returned by this function. The returned object must be freed by calling
-// |socket_free|. Returns NULL on failure.
+// when it is returned by this function. The returned object must be freed by
+// calling |socket_free|. Returns NULL on failure.
socket_t* socket_new(void);
// Returns a new socket object backed by |fd|. The socket object is in whichever
// state |fd| is in when it was passed to this function. The returned object
-// must
-// be freed by calling |socket_free|. Returns NULL on failure. If this function
-// is successful, ownership of |fd| is transferred and the caller must not close
-// it.
+// must be freed by calling |socket_free|. Returns NULL on failure. If this
+// function is successful, ownership of |fd| is transferred and the caller must
+// not close it.
socket_t* socket_new_from_fd(int fd);
// Frees a socket object created by |socket_new| or |socket_accept|. |socket|
-// may
-// be NULL. If the socket was connected, it will be disconnected.
+// may be NULL. If the socket was connected, it will be disconnected.
void socket_free(socket_t* socket);
// Puts |socket| in listening mode for incoming TCP connections on the specified
@@ -58,9 +55,8 @@
bool socket_listen(const socket_t* socket, port_t port);
// Blocks on a listening socket, |socket|, until a client connects to it.
-// Returns
-// a connected socket on success, NULL on failure. The returned object must be
-// freed by calling |socket_free|. |socket| may not be NULL.
+// Returns a connected socket on success, NULL on failure. The returned object
+// must be freed by calling |socket_free|. |socket| may not be NULL.
socket_t* socket_accept(const socket_t* socket);
// Reads up to |count| bytes from |socket| into |buf|. This function will not
@@ -90,38 +86,30 @@
// This function performs the same write operation as |socket_write| and also
// sends the file descriptor |fd| over the socket to a remote process. Ownership
// of |fd| transfers to this function and the descriptor must not be used any
-// longer.
-// If |fd| is INVALID_FD, this function behaves the same as |socket_write|.
+// longer. If |fd| is INVALID_FD, this function behaves the same as
+// |socket_write|.
ssize_t socket_write_and_transfer_fd(const socket_t* socket, const void* buf,
size_t count, int fd);
// Returns the number of bytes that can be read from |socket| without blocking.
-// On error,
-// this function returns -1. |socket| may not be NULL.
+// On error, this function returns -1. |socket| may not be NULL.
//
// Note: this function should not be part of the socket interface. It is only
-// provided as
-// a stop-gap until we can refactor away code that depends on a priori
-// knowledge of
-// the byte count. Do not use this function unless you need it while
-// refactoring
-// legacy bluedroid code.
+// provided as a stop-gap until we can refactor away code that depends on
+// a priori knowledge of the byte count. Do not use this function unless
+// you need it while refactoring legacy bluedroid code.
ssize_t socket_bytes_available(const socket_t* socket);
// Registers |socket| with the |reactor|. When the socket becomes readable,
-// |read_cb|
-// will be called. When the socket becomes writeable, |write_cb| will be called.
-// The
-// |context| parameter is passed, untouched, to each of the callback routines.
-// Neither
-// |socket| nor |reactor| may be NULL. |read_cb|, |write_cb|, and |context| may
-// be NULL.
+// |read_cb| will be called. When the socket becomes writeable, |write_cb| will
+// be called. The |context| parameter is passed, untouched, to each of the
+// callback routines. Neither |socket| nor |reactor| may be NULL. |read_cb|,
+// |write_cb|, and |context| may be NULL.
void socket_register(socket_t* socket, reactor_t* reactor, void* context,
socket_cb read_cb, socket_cb write_cb);
// Unregisters |socket| from whichever reactor it is registered with, if any.
-// This
-// function is idempotent.
+// This function is idempotent.
void socket_unregister(socket_t* socket);
#ifdef __cplusplus