Lang. & formatting fixes in API docs.

include/netdef.h

@@ -27,7 +27,7 @@
 /**
  * @brief   Get the full path that a @ref NetplanNetDefinition will be written to by its backend renderer.
  * @details Copies a `NUL`-terminated string into a sized @p out_buffer. If the
- *          buffer is too small its content will not be `NUL`-terminated.
+ *          buffer is too small, its content is not `NUL`-terminated.
  * @note    Used by the NetworkManager YAML backend but also applicable to the systemd-networkd renderer.
  * @param[in]  netdef       The @ref NetplanNetDefinition to query
  * @param[in]  ssid         Wi-Fi SSID of this connection, or `NULL`
@@ -42,7 +42,7 @@ netplan_netdef_get_output_filename(const NetplanNetDefinition* netdef, const cha
 /**
  * @brief   Get the origin filepath of a given @ref NetplanNetDefinition.
  * @details Copies a `NUL`-terminated string into a sized @p out_buffer. If the
- *          buffer is too small its content will not be `NUL`-terminated.
+ *          buffer is too small, its content is not `NUL`-terminated.
  * @param[in]  netdef          The @ref NetplanNetDefinition to query
  * @param[out] out_buffer      A pre-allocated buffer to write the output string into, owned by the caller
  * @param[in]  out_buffer_size The maximum size (in bytes) available for @p out_buffer
@@ -71,7 +71,7 @@ netplan_netdef_get_type(const NetplanNetDefinition* netdef);
 /**
  * @brief   Get the Netplan ID of a given @ref NetplanNetDefinition.
  * @details Copies a `NUL`-terminated string into a sized @p out_buffer. If the
- *          buffer is too small its content will not be `NUL`-terminated.
+ *          buffer is too small, its content is not `NUL`-terminated.
  * @param[in]  netdef          The @ref NetplanNetDefinition to query
  * @param[out] out_buffer      A pre-allocated buffer to write the output string into, owned by the caller
  * @param[in]  out_buffer_size The maximum size (in bytes) available for @p out_buffer
@@ -129,7 +129,7 @@ netplan_netdef_get_sriov_link(const NetplanNetDefinition* netdef);
 /**
  * @brief   Get the `set-name` setting of a given @ref NetplanNetDefinition.
  * @details Copies a `NUL`-terminated string into a sized @p out_buffer. If the
- *          buffer is too small its content will not be `NUL`-terminated.
+ *          buffer is too small, its content is not `NUL`-terminated.
  * @note    This is unrelated to the `match.name` setting.
  * @param[in]  netdef          The @ref NetplanNetDefinition to query
  * @param[out] out_buffer      A pre-allocated buffer to write the output string into, owned by the caller
@@ -152,7 +152,7 @@ netplan_netdef_has_match(const NetplanNetDefinition* netdef);
 
 /**
  * @brief   Check if a @ref NetplanNetDefinition matches on given interface parameters.
- * @details If defined in @p netdef calculate if it would match on given @p mac AND @p name AND @p driver_name parameters.
+ * @details If defined in @p netdef, calculate if it would match on given @p mac AND @p name AND @p driver_name parameters.
  * @note    Matching a single driver out of a list given in the YAML configuration is enough to satisfy the condition.
  * @param[in] netdef The @ref NetplanNetDefinition to query
  * @param[in] name   The interface name match, optionally using shell wildcard patterns (`fnmatch()`)
@@ -182,7 +182,7 @@ netplan_netdef_get_dhcp6(const NetplanNetDefinition* netdef);
 /**
  * @brief   Get the `macaddress` setting of a given @ref NetplanNetDefinition.
  * @details Copies a `NUL`-terminated string into a sized @p out_buffer. If the
- *          buffer is too small its content will not be `NUL`-terminated.
+ *          buffer is too small, its content is not `NUL`-terminated.
  * @note    This is unrelated to the `match.macaddress` setting.
  * @param[in]  netdef          The @ref NetplanNetDefinition to query
  * @param[out] out_buffer      A pre-allocated buffer to write the output string into, owned by the caller

include/parse-nm.h

@@ -30,7 +30,7 @@
  * @brief   Parse a NetworkManager keyfile into a @ref NetplanNetDefinition struct.
  * @param[in]  npp      The @ref NetplanParser object that should contain the parsed data
  * @param[in]  filename Full path to the NetworkManager keyfile
- * @param[out] error    Will be filled with a @ref NetplanError in case of failure
+ * @param[out] error    Filled with a @ref NetplanError in case of failure
  * @return              Indication of success or failure
  */
 NETPLAN_PUBLIC gboolean

include/parse.h

@@ -57,7 +57,7 @@ netplan_parser_clear(NetplanParser **npp);
  * @brief Parse a given YAML file and create or update the list of @ref NetplanNetDefinition inside @p npp.
  * @param[in]  npp      The @ref NetplanParser object that should contain the parsed data
  * @param[in]  filename Full path to a Netplan YAML configuration file
- * @param[out] error    Will be filled with a @ref NetplanError in case of failure
+ * @param[out] error    Filled with a @ref NetplanError in case of failure
  * @return              Indication of success or failure
  */
 NETPLAN_PUBLIC gboolean
@@ -68,7 +68,7 @@ netplan_parser_load_yaml(NetplanParser* npp, const char* filename, NetplanError*
           @ref NetplanNetDefinition inside @p npp.
  * @param[in]  npp      The @ref NetplanParser object that should contain the parsed data
  * @param[in]  input_fd File descriptor reference to a Netplan YAML configuration file
- * @param[out] error    Will be filled with a @ref NetplanError in case of failure
+ * @param[out] error    Filled with a @ref NetplanError in case of failure
  * @return              Indication of success or failure
  */
 NETPLAN_PUBLIC gboolean
@@ -82,35 +82,35 @@ netplan_parser_load_yaml_from_fd(NetplanParser* npp, int input_fd, NetplanError*
  *        `/etc/netplan/`, which shadow files in `/usr/lib/netplan/`.
  * @param[in]  npp     The @ref NetplanParser object that should contain the parsed data
  * @param[in]  rootdir If not `NULL`, parse configuration from this root directory (useful for testing)
- * @param[out] error   Will be filled with a @ref NetplanError in case of failure
+ * @param[out] error   Filled with a @ref NetplanError in case of failure
  * @return             Indication of success or failure
  */
 NETPLAN_PUBLIC gboolean
 netplan_parser_load_yaml_hierarchy(NetplanParser* npp, const char* rootdir, NetplanError** error);
 
 /**
- * @brief   Parse a Netplan YAML config file from a file descriptor, containing settings
+ * @brief   Parse a Netplan YAML configuration file from a file descriptor, containing settings
  *          that are about to be deleted (e.g. `some.setting=NULL`).
  * @details The `NULL`-settings are ignored when parsing subsequent YAML files.
  * @param[in]  npp      The @ref NetplanParser object that should contain the parsed data
  * @param[in]  input_fd File descriptor reference to a Netplan YAML configuration file
- * @param[out] error    Will be filled with a @ref NetplanError in case of failure
+ * @param[out] error    Filled with a @ref NetplanError in case of failure
  * @return              Indication of success or failure
  */
 NETPLAN_PUBLIC gboolean
 netplan_parser_load_nullable_fields(NetplanParser* npp, int input_fd, NetplanError** error);
 
 /**
- * @brief   Parse a Netplan YAML config file from a file descriptor, containing special settings that
- *          are supposed to be overriden inside the YAML hierarchy by the resulting "origin-hint" output file.
+ * @brief   Parse a Netplan YAML configuration file from a file descriptor, containing special settings that
+ *          are to be overriden inside the YAML hierarchy by the resulting "origin-hint" output file.
  * @details Global settings (like `renderer`) or @ref NetplanNetDefinition, defined in @p input_fd
- *          shall be ignored from the existing YAML hierarchy, as @p input_fd configuration is
- *          supposed to override those settings via the "origin-hint" output file.
+ *          are ignored in the existing YAML hierarchy because the @p input_fd configuration
+ *          overrides those settings via the "origin-hint" output file.
  * @note    Those settings are supposed to be parsed from the "origin-hint" output file given in @p constraint only.
  * @param[in]  npp        The @ref NetplanParser object that should contain the parsed data
  * @param[in]  input_fd   File descriptor reference to a Netplan YAML configuration file, which would become the "origin-hint" output file afterwards
  * @param[in]  constraint Basename of the "origin-hint" output file
- * @param[out] error      Will be filled with a @ref NetplanError in case of failure
+ * @param[out] error      Filled with a @ref NetplanError in case of failure
  * @return                Indication of success or failure
  */
 NETPLAN_PUBLIC gboolean

include/state.h

@@ -51,10 +51,10 @@ netplan_state_clear(NetplanState** np_state);
 
 /**
  * @brief   Validate pre-parsed Netplan configuration data inside a @ref NetplanParser and import them into a @ref NetplanState.
- * @details This will transfer ownership of the contained data from @p npp to @p np_state and clean up by calling @ref netplan_parser_reset.
+ * @details This transfers ownership of the contained data from @p npp to @p np_state and cleans up by calling @ref netplan_parser_reset.
  * @param[in]  np_state The @ref NetplanState to be filled with validated Netplan configuration from @p npp
  * @param[in]  npp      The @ref NetplanParser containing unvalidated Netplan configuration from raw inputs
- * @param[out] error    Will be filled with a @ref NetplanError in case of failure
+ * @param[out] error    Filled with a @ref NetplanError in case of failure
  * @return              Indication of success or failure
  */
 NETPLAN_PUBLIC gboolean
@@ -80,21 +80,21 @@ netplan_state_get_netdef(const NetplanState* np_state, const char* id);
 
 /**
  * @brief Get the global @ref NetplanBackend defined in this @ref NetplanState.
- * @note  This will be the default fallback backend to render any contained @ref NetplanNetDefinition on, if not otherwise specified.
+ * @note  This is the default fallback backend to render any contained @ref NetplanNetDefinition on, if not otherwise specified.
  * @param[in] np_state The @ref NetplanState to query
  * @return             Enumeration value, specifiying the @ref NetplanBackend
  */
 NETPLAN_PUBLIC NetplanBackend
 netplan_state_get_backend(const NetplanState* np_state);
 
 /**
- * @brief   Write the selected YAML file, filtered to the data relevant to this file.
- * @details Writes out all @ref NetplanNetDefinition settings that originate from the specified file,
+ * @brief   Write the selected YAML file filtered to the data relevant to this file.
+ * @details Writes all @ref NetplanNetDefinition settings that originate from the specified file,
  *          as well as those without any given origin. Any data that's assigned to another file is ignored.
  * @param[in]  np_state The @ref NetplanState for which to generate the config
- * @param[in]  filename Relevant file basename (e.g. origin-hint.yaml)
+ * @param[in]  filename Relevant file basename (e.g. `origin-hint.yaml`)
  * @param[in]  rootdir  If not `NULL`, generate configuration in this root directory (useful for testing)
- * @param[out] error    Will be filled with a @ref NetplanError in case of failure
+ * @param[out] error    Filled with a @ref NetplanError in case of failure
  * @return              Indication of success or failure
  */
 NETPLAN_PUBLIC gboolean
@@ -106,12 +106,12 @@ netplan_state_write_yaml_file(
 
 /**
  * @brief   Update all the YAML files that were used to create this @ref NetplanState.
- * @details Any data that hasn't an associated filepath will use the @p default_filename
- *          output file in the standard config directory.
- * @param[in]  np_state The @ref NetplanState for which to generate the config
- * @param[in]  default_filename Default config file, cannot be `NULL` or empty
+ * @details Data that has no associated filepath uses the @p default_filename
+ *          output file in the standard configuration directory.
+ * @param[in]  np_state The @ref NetplanState for which to generate the configuration
+ * @param[in]  default_filename Default configuration file; cannot be `NULL` or empty
  * @param[in]  rootdir  If not `NULL`, generate configuration in this root directory (useful for testing)
- * @param[out] error    Will be filled with a @ref NetplanError in case of failure
+ * @param[out] error    Filled with a @ref NetplanError in case of failure
  * @return              Indication of success or failure
  */
 NETPLAN_PUBLIC gboolean
@@ -124,9 +124,9 @@ netplan_state_update_yaml_hierarchy(
 /**
  * @brief   Dump the whole @ref NetplanState into a single YAML file.
  * @details Ignoring the origin of each @ref NetplanNetDefinition.
- * @param[in]  np_state The @ref NetplanState for which to generate the config
+ * @param[in]  np_state The @ref NetplanState for which to generate the configuration
  * @param[in]  out_fd   File descriptor to an opened file into which to dump the content
- * @param[out] error    Will be filled with a @ref NetplanError in case of failure
+ * @param[out] error    Filled with a @ref NetplanError in case of failure
  * @return              Indication of success or failure
  */
 NETPLAN_PUBLIC gboolean
@@ -137,10 +137,10 @@ netplan_state_dump_yaml(
 
 /**
  * @brief Generate the Netplan YAML configuration for the selected @ref NetplanNetDefinition.
- * @param[in]  np_state @ref NetplanState (as pointer), the global state to which the netdef belongs
+ * @param[in]  np_state @ref NetplanState (as pointer), the global state to which the `netdef` belongs
  * @param[in]  netdef   @ref NetplanNetDefinition (as pointer), the data to be serialized
  * @param[in]  rootdir  If not `NULL`, generate configuration in this root directory (useful for testing)
- * @param[out] error    Will be filled with a @ref NetplanError in case of failure
+ * @param[out] error    Filled with a @ref NetplanError in case of failure
  * @return              Indication of success or failure
  */
 NETPLAN_PUBLIC gboolean
@@ -176,10 +176,10 @@ netplan_state_iterator_has_next(const NetplanStateIterator* iter);
 
 /**
  * @brief   Write generic NetworkManager configuration to disk.
- * @details This configures global settings, independent of @ref NetplanNetDefinition data, like udev blocklisting to make NetworkManager ignore certain interfaces using `[device].managed=false` or `NM_MANAGED=0`.
+ * @details This configures global settings, independent of @ref NetplanNetDefinition data, such as udev blocklisting to make NetworkManager ignore certain interfaces using `[device].managed=false` or `NM_MANAGED=0`.
  * @param[in]  np_state The @ref NetplanState to read settings from
  * @param[in]  rootdir  If not `NULL`, generate configuration in this root directory (useful for testing)
- * @param[out] error    Will be filled with a @ref NetplanError in case of failure
+ * @param[out] error    Filled with a @ref NetplanError in case of failure
  * @return              Indication of success or failure
  */
 NETPLAN_PUBLIC gboolean
@@ -190,10 +190,10 @@ netplan_state_finish_nm_write(
 
 /**
  * @brief   Write generic Open vSwitch  configuration to disk.
- * @details This configures global settings, independent of @ref NetplanNetDefinition data, like patch ports, SSL configuration or the `netplan-ovs-cleanup.service` unit.
+ * @details This configures global settings, independent of @ref NetplanNetDefinition data, such as patch ports, SSL configuration or the `netplan-ovs-cleanup.service` unit.
  * @param[in]  np_state The @ref NetplanState to read settings from
  * @param[in]  rootdir  If not `NULL`, generate configuration in this root directory (useful for testing)
- * @param[out] error    Will be filled with a @ref NetplanError in case of failure
+ * @param[out] error    Filled with a @ref NetplanError in case of failure
  * @return              Indication of success or failure
  */
 NETPLAN_PUBLIC gboolean
@@ -204,10 +204,10 @@ netplan_state_finish_ovs_write(
 
 /**
  * @brief   Write generic SR-IOV  configuration to disk.
- * @details This configures global settings, independent of @ref NetplanNetDefinition data, like udev rules or the `netplan-sriov-rebind.service` unit.
+ * @details This configures global settings, independent of @ref NetplanNetDefinition data, such as udev rules or the `netplan-sriov-rebind.service` unit.
  * @param[in]  np_state The @ref NetplanState to read settings from
  * @param[in]  rootdir  If not `NULL`, generate configuration in this root directory (useful for testing)
- * @param[out] error    Will be filled with a @ref NetplanError in case of failure
+ * @param[out] error    Filled with a @ref NetplanError in case of failure
  * @return              Indication of success or failure
  */
 NETPLAN_PUBLIC gboolean

include/types.h

@@ -23,7 +23,7 @@
 
 #pragma once
 
-/// Symbols that are considered part of Netplan's public API.
+/// Symbols that are considered part of Netplan public API.
 #define NETPLAN_PUBLIC __attribute__ ((visibility("default")))
 /// Symbols that are used internally by Netplan.
 /// @warning Do not use those symbols in an external codebase, they might be dropped or changed without notice.
@@ -32,7 +32,7 @@
 /// @note Those symbols will be dropped in the future.
 #define NETPLAN_DEPRECATED __attribute__ ((deprecated))
 
-/// Error of value `-2`, to indicate an issue with the buffer.
+/// Error of value `-2` to indicate an issue with the buffer.
 #define NETPLAN_BUFFER_TOO_SMALL -2
 
 
@@ -101,8 +101,8 @@ typedef struct _NetplanStateIterator NetplanStateIterator;
 
 /**
  * @brief   Defining a non-opaque placeholder type for the private `struct netplan_state_iterator`.
- * @details Do not use directly. Instead use @ref NetplanStateIterator. Enables consumers to place the interator at the stack.
- * @note    The idea is based on GLib's implementation of iterators.
+ * @details Do not use directly. Use @ref NetplanStateIterator instead. Enables consumers to place the iterator at the stack.
+ * @note    The idea is based on the GLib implementation of iterators.
  */
 struct _NetplanStateIterator {
     void* placeholder;
@@ -159,7 +159,7 @@ enum NETPLAN_EMITTER_ERRORS {
 /**
  * @brief   Errors for domain @ref NETPLAN_FORMAT_ERROR.
  * @details Such errors are generic errors emitted from contexts where information
- *          like the file name is not known.
+ *          such as the file name is not known.
  */
 enum NETPLAN_FORMAT_ERRORS {
     NETPLAN_ERROR_FORMAT_INVALID_YAML,