Merge pull request #1994 from UncleGrumpy/doc_fixes

Documentation fixes

These changes are made under both the "Apache 2.0" and the "GNU Lesser General
Public License 2.1 or later" license terms (dual license).

SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later

Author: bettio

libs/estdlib/src/supervisor.erl

@@ -18,8 +18,6 @@
 % SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later
 %
 
--module(supervisor).
-
 %%-----------------------------------------------------------------------------
 %% @doc An implementation of the Erlang/OTP supervisor interface.
 %%
@@ -39,6 +37,7 @@
 %% </ul>
 %% @end
 %%-----------------------------------------------------------------------------
+-module(supervisor).
 
 -behavior(gen_server).
 

src/libAtomVM/atom_table.h

@@ -82,7 +82,7 @@ bool atom_table_is_atom_ref_ascii(struct AtomTable *table, atom_ref_t atom);
  * @details returned pointer is not null terminated
  *
  * @param   table atom table
- * @param   atom_index index of the atom to get the representation of
+ * @param   index index of the atom to get the representation of
  * @param   out_len on output, size of the character data
  */
 const uint8_t *atom_table_get_atom_string(struct AtomTable *table, atom_index_t index, size_t *out_len);
@@ -93,6 +93,7 @@ const uint8_t *atom_table_get_atom_string(struct AtomTable *table, atom_index_t
  * @details Write module:function/arity to the supplied buffer.  This function will abort
  *          if the written module, function, and arity are longer than the supplied
  *          buffer size.
+ * @param   table atom table
  * @param   buf the buffer to write into
  * @param   buf_size the amount of room in the buffer
  * @param   module the module name

src/libAtomVM/context.h

@@ -518,7 +518,6 @@ struct Monitor *monitor_new(term monitor_pid, uint64_t ref_ticks, bool is_monito
  * @param monitor_process_id monitored process id
  * @param monitor_name name of the monitor (atom)
  * @param ref_ticks reference of the monitor
- * @param is_monitoring if ctx is the monitoring process
  * @return the allocated monitor or NULL if allocation failed
  */
 struct Monitor *monitor_registeredname_monitor_new(int32_t monitor_process_id, term monitor_name, uint64_t ref_ticks);

src/libAtomVM/dist_nifs.h

@@ -48,7 +48,7 @@ extern const struct Nif dist_ctrl_put_data_nif;
 struct DistConnection;
 
 /**
- * @doc Enqueue a message to be sent to a remote process.
+ * @brief Enqueue a message to be sent to a remote process.
  * This function may raise a badarg error following OTP if target is incorrect.
  * @param target external pid or a tuple {atom(), node()} to refer to a remote
  * registered process
@@ -60,8 +60,7 @@ struct DistConnection;
 term dist_send_message(term target, term payload, Context *ctx);
 
 /**
- * @doc Setup a monitor on a local process for a distributed process.
- * @end
+ * @brief Setup a monitor on a local process for a distributed process.
  * @param conn_obj object of the connection
  * @param from_pid remote pid setting up the monitor
  * @param target_proc atom (for registered process) or pid of the local
@@ -72,28 +71,27 @@ term dist_send_message(term target, term payload, Context *ctx);
 term dist_monitor(struct DistConnection *conn_obj, term from_pid, term target_proc, term monitor_ref, Context *ctx);
 
 /**
- * @doc Send a spawn reply signal to a node
- * @end
- * @param conn_obj object of the connection
+ * @brief Send a spawn reply signal to a node
  * @param req_id reference identifying the request
  * @param to_pid (remote) process id identifying the caller
  * @param link if a link was created
  * @param monitor if a monitor was created
  * @param result pid of the spawned process or atom for an error
- * @param ctx context for memory allocation
+ * @param connection object of the connection
+ * @param global context for memory allocation
  */
 void dist_spawn_reply(term req_id, term to_pid, bool link, bool monitor, term result, struct DistConnection *connection, GlobalContext *global);
 
 /**
- * @doc Send a link exit signal (PAYLOAD_EXIT)
+ * @brief Send a link exit signal (PAYLOAD_EXIT)
  * @param monitor structure with node, process_id, serial and creation
  * @param reason reason to send as the payload
  * @param ctx process that is exiting.
  */
 void dist_send_payload_exit(struct LinkRemoteMonitor *monitor, term reason, Context *ctx);
 
 /**
- * @doc Send a link signal (LINK)
+ * @brief Send a link signal (LINK)
  * @param from_pid the pid linking to
  * @param to_pid the (remote) pid to link to
  * @param ctx context for memory allocation
@@ -103,7 +101,7 @@ void dist_send_payload_exit(struct LinkRemoteMonitor *monitor, term reason, Cont
 term dist_send_link(term from_pid, term to_pid, Context *ctx);
 
 /**
- * @doc Send an unlink id signal (UNLINK_ID), silently do nothing if node is
+ * @brief Send an unlink id signal (UNLINK_ID), silently do nothing if node is
  * not connected
  * @param unlink_id unique id of the unlink operation
  * @param from_pid the pid linking to
@@ -113,7 +111,7 @@ term dist_send_link(term from_pid, term to_pid, Context *ctx);
 void dist_send_unlink_id(uint64_t unlink_id, term from_pid, term to_pid, Context *ctx);
 
 /**
- * @doc Send an unlink id ack signal (UNLINK_ID_ACK), silently do nothing if node is
+ * @brief Send an unlink id ack signal (UNLINK_ID_ACK), silently do nothing if node is
  * not connected
  * @param unlink_id unique id of the unlink operation
  * @param from_pid the pid linking to

src/libAtomVM/externalterm.h

@@ -54,7 +54,6 @@ enum ExternalTermResult
  * WARNING: This function may call the GC, which may render the input binary
  * invalid. See `externalterm_from_binary_with_roots'
  * @param ctx the context that owns the memory that will be allocated.
- * @param dst a pointer to a term that will contain the binary encoded term.
  * @param binary the binary.
  * @param bytes_read the number of bytes read from the input binary.
  * @returns the term deserialized from the input term, or an invalid term, if

src/libAtomVM/globalcontext.h

@@ -402,7 +402,8 @@ void globalcontext_maybe_unregister_process_id(GlobalContext *glb, int process_i
  *
  * @details Inserts an atom into the global atoms table and returns its id.
  * @param glb the global context.
- * @param atom_string the atom string that will be added to the global atoms table, it will not be copied so it must stay allocated and valid.
+ * @param atom_data the atom data
+ * @param atom_len the atom data length
  * @param copy if `true`, make a copy of the input atom_string if the atom is not already in the table.  The table
  * assumes "ownership" of the allocated memory.
  * @returns newly added atom id or term_invalid_term() in case of failure.
@@ -514,7 +515,7 @@ Module *globalcontext_get_module(GlobalContext *global, atom_index_t module_name
  * not check if the module is already loaded and allocates a new module
  * structure.
  * @param global the global context.
- * @param module_name_atom the module name.
+ * @param module_name the module name.
  * @returns a pointer to a Module struct or NULL if the module could not be
  * found.
  */

src/libAtomVM/module.h

@@ -175,6 +175,7 @@ enum ModuleLoadResult
  * @param index the modules import table offset to begin searching.
  * @param module_atom module name atom string.
  * @param function_atom function name atom string.
+ * @param glb the global context.
  */
 void module_get_imported_function_module_and_name(const Module *this_module, int index, AtomString *module_atom, AtomString *function_atom, GlobalContext *glb);
 #endif

src/libAtomVM/sys.h

@@ -244,7 +244,7 @@ uint64_t sys_monotonic_time_u64_to_ms(uint64_t t);
  * and returns a pointer to a Module struct. This function is called if loading
  * from avm packs failed and may return NULL if there is no support for files.
  * @param global the global context.
- * @param module_name the name of the BEAM file (e.g. "mymodule.beam").
+ * @param path to the named BEAM file (e.g. "mymodule.beam").
  */
 Module *sys_load_module_from_file(GlobalContext *global, const char *path);
 

src/libAtomVM/term.h

@@ -1948,7 +1948,7 @@ static inline term term_make_external_port_number(term node, uint64_t number, ui
 /**
  * @brief Get the name of a node for a given external thing
  *
- * @param term external term
+ * @param t external term
  * @return the name of the node
  */
 static inline term term_get_external_node(term t)
@@ -1963,7 +1963,7 @@ static inline term term_get_external_node(term t)
 /**
  * @brief Get the creation for a given external thing
  *
- * @param term external term
+ * @param t external term
  * @return the serial of the external pid
  */
 static inline uint32_t term_get_external_node_creation(term t)
@@ -1978,7 +1978,7 @@ static inline uint32_t term_get_external_node_creation(term t)
 /**
  * @brief Get the process id of an external pid
  *
- * @param term external pid
+ * @param t external pid
  * @return the process id of the external pid
  */
 static inline uint32_t term_get_external_pid_process_id(term t)
@@ -1993,7 +1993,7 @@ static inline uint32_t term_get_external_pid_process_id(term t)
 /**
  * @brief Get the serial of an external pid
  *
- * @param term external term
+ * @param t external term
  * @return the serial of the external pid
  */
 static inline uint32_t term_get_external_pid_serial(term t)
@@ -2008,7 +2008,7 @@ static inline uint32_t term_get_external_pid_serial(term t)
 /**
  * @brief Get the port number of an external port
  *
- * @param term external port
+ * @param t external port
  * @return the port number of the external port
  */
 static inline uint64_t term_get_external_port_number(term t)
@@ -2064,7 +2064,7 @@ static inline term term_make_external_reference(term node, uint16_t len, uint32_
 /**
  * @brief Get the number of words of an external reference
  *
- * @param term external term
+ * @param t external term
  * @return the number of words of the external reference (from 1 to 5)
  */
 static inline uint32_t term_get_external_reference_len(term t)
@@ -2088,7 +2088,7 @@ static inline uint32_t term_get_external_reference_len(term t)
 /**
  * @brief Get the words of an external reference
  *
- * @param term external term
+ * @param t external term
  * @return a pointer to (len) words of the external reference
  */
 static inline const uint32_t *term_get_external_reference_words(term t)