From 9e8d063448603922bcbd5b64cf45b5473bd1455e Mon Sep 17 00:00:00 2001
From: Patrick McDermott <patrick.mcdermott@libiquity.com>
Date: Sat, 29 Dec 2018 14:28:10 -0500
Subject: ob_parse_version(): Document

---
diff --git a/lib/metadata.sh b/lib/metadata.sh
index 5628a18..c7c62a6 100644
--- a/lib/metadata.sh
+++ b/lib/metadata.sh
@@ -75,6 +75,25 @@ ob_validate_binary_name()
 	return ${?}
 }
 
+## @brief Parse a source package version
+## @details \fBob_parse_version\fP validates and parses a source package version
+##          identifier using the metadata plugin selected at libopkbuild's build
+##          time.  Parsing is limited to extracting the entire upstream version
+##          and distribution revision.
+## @option -u upstreamver_var The name of the variable in which to store the
+##                            upstream version.
+## @option -d distrev_var     The name of the variable in which to store the
+##                            distribution revision.
+## @operand version req The version to validate and parse.
+## @return Returns 0 on success; 1 on invalid \fIversion\fP; or 125 if given an
+##         invalid variable name as an argument to \fB-u\fP or \fB-d\fP, an
+##         invalid option, or an incorrect number of operands.
+## @pure maybe This function has side effects when used with either or both of
+##             the \fB-u\fP and \fB-d\fP options.  Without these options, this
+##             function only validates a version identifier.  The purpose of
+##             this function is mainly to extract version components using these
+##             options, so in practice this function is generally not
+##             subshell-safe.
 ob_parse_version()
 {
 	local opt=
diff --git a/man/local.mk b/man/local.mk
index e213d34..62d8b7a 100644
--- a/man/local.mk
+++ b/man/local.mk
@@ -40,6 +40,7 @@ man3_MANS = \
 	%reldir%/ob_parse_changelog.3 \
 	%reldir%/ob_parse_control.3 \
 	%reldir%/ob_parse_dep.3 \
+	%reldir%/ob_parse_version.3 \
 	%reldir%/ob_reduce_deps.3 \
 	%reldir%/ob_set_substvar.3 \
 	%reldir%/ob_set_text_domain.3 \
--
cgit v0.9.1