Documentation fixes and cleanup:

* Add PackagerV3 and BuildConfig public APIs to documentation index
* Remove StreamV3 references from ModuleIndex documentation
* Fix PackagerV3 and other broken documentation links

Signed-off-by: Merlin Mathesius <[email protected]>

Author: mmathesius

modulemd/include/modulemd-2.0/modulemd-module-index.h

@@ -32,22 +32,18 @@ G_BEGIN_DECLS
  * This object provides an interface to the complete metadata read from a
  * repository or manually added to this object.
  *
- * NOTE: When adding or updating this object from YAML, all
- * #ModulemdModuleStream will be automatically upgraded to match the stream
- * mdversion set for the index, and all #ModulemdDefaults objects imported will
- * be automatically upgraded to match the highest version of that object that
- * has been previously seen. This means, for example, that if the repository
- * has a mix of #ModulemdModuleStreamV1 and #ModulemdModuleStreamV2 objects,
- * and the index's stream mdversion is set to V2, the index will contain only
- * #ModulemdModuleStreamV2. You can check the versions the index upgraded to
- * with the modulemd_module_index_get_stream_mdversion() and
+ * NOTE: When adding or updating this object from YAML, all objects imported
+ * will be automatically upgraded to match the highest version of that object
+ * that is seen. This means that if the repository has a mix of
+ * #ModulemdModuleStreamV1 and #ModulemdModuleStreamV2 objects, the index will
+ * contain only #ModulemdModuleStreamV2. You can check the versions the index
+ * upgraded to with the modulemd_module_index_get_stream_mdversion() and
  * modulemd_module_index_get_defaults_mdversion(). If your application would
  * prefer to always work with a particular stream or defaults version (such as
- * to avoid extra branching logic), modulemd_set_default_stream_mdversion() can
- * be used before creating the index to force #ModulemdModuleStream objects to
- * be upgraded to the desired stream mdversion and
- * modulemd_module_index_upgrade_defaults() function can be used to force the
- * contents of the index to upgrade #ModulemdDefaults to the specified version.
+ * to avoid extra branching logic), the modulemd_module_index_upgrade_streams()
+ * and modulemd_module_index_upgrade_defaults() functions can be used to force
+ * the contents of the index to upgrade to those versions.
+ *
  * Interacting with #ModulemdModuleIndex is relatively simple. A common Python
  * example for working with Fedora repodata might be (assuming the metadata has
  * already been read into strings):

modulemd/include/modulemd-2.0/modulemd-packager-v3.h

@@ -39,7 +39,7 @@ G_DECLARE_FINAL_TYPE (
 /**
  * MMD_PACKAGER_DEFAULT_MODULE_LICENSE:
  *
- * The ModulePackager v3 default module metadata license.
+ * The #ModulemdPackagerV3 default module metadata license.
  *
  * Since: 2.11
  */
@@ -50,12 +50,12 @@ G_DECLARE_FINAL_TYPE (
  * @MD_PACKAGER_VERSION_ERROR: Represents an error handling module stream
  * version.
  * @MD_PACKAGER_VERSION_UNSET: Represents an unset module stream version.
- * @MD_PACKAGER_VERSION_TWO: Represents v2 of the #ModulemdPackager
+ * @MD_PACKAGER_VERSION_TWO: Represents v2 of the ModulePackager
  * metadata format. Since: 2.11
- * @MD_PACKAGER_VERSION_THREE: Represents v3 of the #ModulemdPackager
+ * @MD_PACKAGER_VERSION_THREE: Represents v3 of the ModulePackager
  * metadata format. Since: 2.11
  * @MD_PACKAGER_VERSION_LATEST: Represents the highest-supported version of
- * the #ModulemdPackager metadata format.
+ * the ModulePackager metadata format.
  *
  * Since: 2.11
  */
@@ -86,6 +86,7 @@ modulemd_packager_v3_new (void);
 
 /**
  * modulemd_packager_v3_copy:
+ * @self: This #ModulemdPackagerV3 object.
  *
  * Returns: (transfer full): A newly-allocated deep-copy of this
  * #ModulemdPackagerV3 object. This object must be freed with g_object_unref().

modulemd/include/private/modulemd-build-config-private.h

@@ -31,7 +31,7 @@ G_BEGIN_DECLS
 /**
  * modulemd_build_config_parse_yaml:
  * @parser: A #yaml_parser_t positioned at the start of a configuration
- * entry of a ModulemdPackager v3 YAML document.
+ * entry of a #ModulemdPackagerV3 YAML document.
  * @strict: Whether to ignore unknown keys in the YAML
  * @error: (out): A #GError explaining any failure to complete the parsing
  *

modulemd/include/private/modulemd-module-stream-private.h

@@ -137,16 +137,14 @@ modulemd_module_stream_validate_component_rpm_arches (GHashTable *components,
 /* Some macros used for copy operations */
 /**
  * STREAM_UPGRADE_IF_SET_FULL:
- * @oldversion: The stream version of @src. Must be literal "v1", "v2", or "v3"
+ * @oldversion: The stream version of @src. Must be literal "v1" or "v2"
  * without the quotes.
- * @newversion: The stream version of @dest. Must be literal "v1", "v2", or "v3"
+ * @newversion: The stream version of @dest. Must be literal "v1" or "v2"
  * without the quotes.
- * @dest: (out): A #ModulemdModuleStreamV1, #ModulemdModuleStreamV2, or
- * #ModulemdModuleStreamV3 object that is the destination to which @property is
- * to be copied.
- * @src: (in): A #ModulemdModuleStreamV1, #ModulemdModuleStreamV2, or
- * #ModulemdModuleStreamV3 object that is the source from which @property is to
- * be copied.
+ * @dest: (out): A #ModulemdModuleStreamV1 or #ModulemdModuleStreamV2 object
+ * that is the destination to which @property is to be copied.
+ * @src: (in): A #ModulemdModuleStreamV1 or #ModulemdModuleStreamV2 object that
+ * is the source from which @property is to be copied.
  * @property: The name of the property to copy. Must be the literal property
  * name, in lower case, without quotes.
  * @locale...: (in): An optional locale that can be provided when @property has
@@ -158,8 +156,8 @@ modulemd_module_stream_validate_component_rpm_arches (GHashTable *components,
  * which should be used instead.
  *
  * This is a helper macro to simplify the coding when copying/upgrading
- * properties between #ModulemdModuleStreamV1, #ModulemdModuleStreamV2, and
- * #ModulemdModuleStreamV3 objects.
+ * properties between #ModulemdModuleStreamV1 and #ModulemdModuleStreamV2
+ * objects.
  *
  * Does nothing if the @src @property is NULL.
  *
@@ -180,14 +178,12 @@ modulemd_module_stream_validate_component_rpm_arches (GHashTable *components,
 
 /**
  * STREAM_COPY_IF_SET:
- * @version: The stream version being copied. Must be literal "v1", "v2", or "v3"
+ * @version: The stream version being copied. Must be literal "v1" or "v2"
  * without the quotes.
- * @dest: (out): A #ModulemdModuleStreamV1, #ModulemdModuleStreamV2, or
- * #ModulemdModuleStreamV3 object that is the destination to which @property is
- * to be copied.
- * @src: (in): A #ModulemdModuleStreamV1, #ModulemdModuleStreamV2, or
- * #ModulemdModuleStreamV3 object that is the source from which @property is to
- * be copied.
+ * @dest: (out): A #ModulemdModuleStreamV1 or #ModulemdModuleStreamV2 object
+ * that is the destination to which @property is to be copied.
+ * @src: (in): A #ModulemdModuleStreamV1 or #ModulemdModuleStreamV2 object that
+ * is the source from which @property is to be copied.
  * @property: The name of the property to copy. Must be the literal property
  * name, in lower case, without quotes.
  *
@@ -204,22 +200,20 @@ modulemd_module_stream_validate_component_rpm_arches (GHashTable *components,
 
 /**
  * STREAM_UPGRADE_IF_SET:
- * @oldversion: The stream version of @src. Must be literal "v1", "v2", or "v3"
+ * @oldversion: The stream version of @src. Must be literal "v1" or "v2"
  * without the quotes.
- * @newversion: The stream version of @dest. Must be literal "v1", "v2", or "v3"
+ * @newversion: The stream version of @dest. Must be literal "v1" or "v2"
  * without the quotes.
- * @dest: (out): A #ModulemdModuleStreamV1, #ModulemdModuleStreamV2, or
- * #ModulemdModuleStreamV3 object that is the destination to which @property is
- * to be copied.
- * @src: (in): A #ModulemdModuleStreamV1, #ModulemdModuleStreamV2, or
- * #ModulemdModuleStreamV3 object that is the source from which @property is to
- * be copied.
+ * @dest: (out): A #ModulemdModuleStreamV1 or #ModulemdModuleStreamV2 object
+ * that is the destination to which @property is to be copied.
+ * @src: (in): A #ModulemdModuleStreamV1 or #ModulemdModuleStreamV2 object that
+ * is the source from which @property is to be copied.
  * @property: The name of the property to copy. Must be the literal property
  * name, in lower case, without quotes.
  *
  * This is a convenience macro to simplify the coding when copying properties
- * between #ModulemdModuleStreamV1, #ModulemdModuleStreamV2, and
- * #ModulemdModuleStreamV3 objects when @src and @dest are different versions.
+ * between #ModulemdModuleStreamV1 and #ModulemdModuleStreamV2 objects when
+ * @src and @dest are different versions.
  *
  * Does nothing if the @src @property is NULL.
  *
@@ -230,22 +224,20 @@ modulemd_module_stream_validate_component_rpm_arches (GHashTable *components,
 
 /**
  * STREAM_COPY_IF_SET_WITH_LOCALE:
- * @version: The stream version being copied. Must be literal "v1", "v2", or "v3"
+ * @version: The stream version being copied. Must be literal "v1" or "v2"
  * without the quotes.
- * @dest: (out): A #ModulemdModuleStreamV1, #ModulemdModuleStreamV2, or
- * #ModulemdModuleStreamV3 object that is the destination to which @property is
- * to be copied.
- * @src: (in): A #ModulemdModuleStreamV1, #ModulemdModuleStreamV2, or
- * #ModulemdModuleStreamV3 object that is the source from which @property is to
- * be copied.
+ * @dest: (out): A #ModulemdModuleStreamV1 or #ModulemdModuleStreamV2 object
+ * that is the destination to which @property is to be copied.
+ * @src: (in): A #ModulemdModuleStreamV1 or #ModulemdModuleStreamV2 object that
+ * is the source from which @property is to be copied.
  * @property: The name of the property to copy. Must be the literal property
  * name, in lower case, without quotes.
  *
  * This is a convenience macro to simplify the coding when copying properties
- * between #ModulemdModuleStreamV1, #ModulemdModuleStreamV2, and
- * #ModulemdModuleStreamV3 objects when both @src and @dest are the same version
- * and @property has possible translations. Only the untranslated (`"C"` locale)
- * version of @property will be copied.
+ * between #ModulemdModuleStreamV1 and #ModulemdModuleStreamV2 objects when
+ * both @src and @dest are the same version and @property has possible
+ * translations. Only the untranslated (`"C"` locale) version of @property will
+ * be copied.
  *
  * Does nothing if the @src @property is NULL.
  *
@@ -256,24 +248,22 @@ modulemd_module_stream_validate_component_rpm_arches (GHashTable *components,
 
 /**
  * STREAM_UPGRADE_IF_SET_WITH_LOCALE:
- * @oldversion: The stream version of @src. Must be literal "v1", "v2", or "v3"
+ * @oldversion: The stream version of @src. Must be literal "v1" or "v2"
  * without the quotes.
- * @newversion: The stream version of @dest. Must be literal "v1", "v2", or "v3"
+ * @newversion: The stream version of @dest. Must be literal "v1" or "v2"
  * without the quotes.
- * @dest: (out): A #ModulemdModuleStreamV1, #ModulemdModuleStreamV2, or
- * #ModulemdModuleStreamV3 object that is the destination to which @property is
- * to be copied.
- * @src: (in): A #ModulemdModuleStreamV1, #ModulemdModuleStreamV2, or
- * #ModulemdModuleStreamV3 object that is the source from which @property is to
- * be copied.
+ * @dest: (out): A #ModulemdModuleStreamV1 or #ModulemdModuleStreamV2 object
+ * that is the destination to which @property is to be copied.
+ * @src: (in): A #ModulemdModuleStreamV1 or #ModulemdModuleStreamV2 object that
+ * is the source from which @property is to be copied.
  * @property: The name of the property to copy. Must be the literal property
  * name, in lower case, without quotes.
  *
  * This is a convenience macro to simply the coding when copying properties
- * between #ModulemdModuleStreamV1, #ModulemdModuleStreamV2, and
- * #ModulemdModuleStreamV3 objects when @src and @dest are different versions
- * and @property has possible translations. Only the untranslated (`"C"` locale)
- * version of @property will be copied.
+ * between #ModulemdModuleStreamV1 and #ModulemdModuleStreamV2 objects when
+ * @src and @dest are different versions and @property has possible
+ * translations. Only the untranslated (`"C"` locale) version of @property will
+ * be copied.
  *
  * Does nothing if the @src @property is NULL.
  *
@@ -285,21 +275,18 @@ modulemd_module_stream_validate_component_rpm_arches (GHashTable *components,
 
 /**
  * STREAM_REPLACE_HASHTABLE:
- * @version: The stream version being replaced. Must be literal "v1", "v2", or "v3"
+ * @version: The stream version being replaced. Must be literal "v1" or "v2"
  * without the quotes.
- * @dest: (out): A #ModulemdModuleStreamV1, #ModulemdModuleStreamV2, or
- * #ModulemdModuleStreamV3 object that is the destination at which @property is
- * being replaced.
- * @src: (in): A #ModulemdModuleStreamV1, #ModulemdModuleStreamV2, or
- * #ModulemdModuleStreamV3 object that is the source from which @property is
- * being replaced.
+ * @dest: (out): A #ModulemdModuleStreamV1 or #ModulemdModuleStreamV2 object
+ * that is the destination at which @property is being replaced.
+ * @src: (in): A #ModulemdModuleStreamV1 or #ModulemdModuleStreamV2 object that
+ * is the source from which @property is being replaced.
  * @property: The name of the #GHashTable property to replace. Must be the
  * literal property name, in lower case, without quotes.
  *
  * This is a convenience macro to simply the coding when replacing #GHashTable
- * properties of #ModulemdModuleStreamV1, #ModulemdModuleStreamV2, and
- * #ModulemdModuleStreamV3 objects when both @src and @dest are the same
- * version.
+ * properties of #ModulemdModuleStreamV1 and #ModulemdModuleStreamV2 objects
+ * when both @src and @dest are the same version.
  *
  * Since: 2.0
  */
@@ -313,21 +300,18 @@ modulemd_module_stream_validate_component_rpm_arches (GHashTable *components,
 
 /**
  * COPY_HASHTABLE_BY_VALUE_ADDER:
- * @dest: (out): A #ModulemdModuleStreamV1, #ModulemdModuleStreamV2, or
- * #ModulemdModuleStreamV3 object that is the destination to which @property is
- * to be copied.
- * @src: (in): A #ModulemdModuleStreamV1, #ModulemdModuleStreamV2, or
- * #ModulemdModuleStreamV3 object that is the source from which @property is to
- * be copied.
+ * @dest: (out): A #ModulemdModuleStreamV1 or #ModulemdModuleStreamV2 object
+ * that is the destination to which @property is to be copied.
+ * @src: (in): A #ModulemdModuleStreamV1 or #ModulemdModuleStreamV2 object that
+ * is the source from which @property is to be copied.
  * @property: The name of the #GHashTable property to copy. Must be the literal
  * property name, in lower case, without quotes.
  * @adder: (in): A pointer to a method of @dest that supports add-on property
  * values.
  *
  * This is a convenience macro to simply the coding when copying #GHashTable
- * properties between #ModulemdModuleStreamV1, #ModulemdModuleStreamV2, and
- * #ModulemdModuleStreamV3 objects when the property is set by using add-on
- * values.
+ * properties between #ModulemdModuleStreamV1 and #ModulemdModuleStreamV2
+ * objects when the property is set by using add-on values.
  *
  * Since: 2.0
  */

modulemd/include/private/modulemd-packager-v3-private.h

@@ -113,9 +113,9 @@ modulemd_packager_v3_parse_yaml (ModulemdSubdocumentInfo *subdoc,
 
 /**
  * modulemd_packager_v3_emit_yaml:
- * @self: This #ModulemdModulePackagerV3 object.
+ * @self: This #ModulemdPackagerV3 object.
  * @emitter: (inout): A libyaml emitter object positioned where the data
- * section of a #ModulemdModulePackagerV3 belongs in the YAML document.
+ * section of a #ModulemdPackagerV3 belongs in the YAML document.
  * @error: (out): A #GError that will return the reason for an emission or
  * validation error.
  *

modulemd/include/private/modulemd-yaml.h

@@ -42,7 +42,7 @@ G_BEGIN_DECLS
  * @MODULEMD_YAML_DOC_TRANSLATIONS: Represents a `modulemd-translations` (see
  * #ModulemdTranslation) YAML document type.
  * @MODULEMD_YAML_DOC_PACKAGER: Represents a `modulemd-packager` document.
- * V2 is a subset of #ModuleStreamV2 containing only the attributes that a
+ * V2 is a subset of #ModulemdModuleStreamV2 containing only the attributes that a
  * package maintainer should modify. V3 (see #ModulemdPackagerV3) is a new YAML
  * document type. Since: 2.9
  * @MODULEMD_YAML_DOC_OBSOLETES: Represents a `modulemd-obsoletes` document (see
@@ -791,7 +791,7 @@ modulemd_yaml_parse_string_string_map (yaml_parser_t *parser, GError **error);
  * validation error.
  *
  * Function for retrieving a hash table from a str/string-set map such as
- * data.dependencies in ModuleStreamV2.
+ * data.dependencies in #ModulemdModuleStreamV2.
  *
  * Returns: (transfer full): A newly-allocated #GHashTable * representing the
  * parsed values. NULL if a parse error occurred and sets @error appropriately.

modulemd/modulemd-docs.xml

@@ -36,6 +36,7 @@
     <chapter>
       <title>Modulemd 2.0 Public API</title>
         <xi:include href="xml/modulemd.xml"/>
+        <xi:include href="xml/modulemd-build-config.xml"/>
         <xi:include href="xml/modulemd-buildopts.xml"/>
         <xi:include href="xml/modulemd-component.xml"/>
         <xi:include href="xml/modulemd-component-module.xml"/>
@@ -51,6 +52,7 @@
         <xi:include href="xml/modulemd-module-stream.xml"/>
         <xi:include href="xml/modulemd-module-stream-v1.xml"/>
         <xi:include href="xml/modulemd-module-stream-v2.xml"/>
+        <xi:include href="xml/modulemd-packager-v3.xml"/>
         <xi:include href="xml/modulemd-profile.xml"/>
         <xi:include href="xml/modulemd-rpm-map-entry.xml"/>
         <xi:include href="xml/modulemd-service-level.xml"/>
@@ -61,7 +63,7 @@
     </chapter>
     <chapter>
       <title>Modulemd 2.0 Private Object Methods</title>
-       <xi:include href="xml/modulemd-build-config.xml"/>
+       <xi:include href="xml/modulemd-build-config-private.xml"/>
        <xi:include href="xml/modulemd-buildopts-private.xml"/>
        <xi:include href="xml/modulemd-component-private.xml"/>
        <xi:include href="xml/modulemd-component-module-private.xml"/>
@@ -75,7 +77,7 @@
        <xi:include href="xml/modulemd-module-stream-private.xml"/>
        <xi:include href="xml/modulemd-module-stream-v1-private.xml"/>
        <xi:include href="xml/modulemd-module-stream-v2-private.xml"/>
-       <xi:include href="xml/modulemd-packager-v3.xml"/>
+       <xi:include href="xml/modulemd-packager-v3-private.xml"/>
        <xi:include href="xml/modulemd-profile-private.xml"/>
        <xi:include href="xml/modulemd-rpm-map-entry-private.xml"/>
        <xi:include href="xml/modulemd-service-level-private.xml"/>