ob_parse_version(): Document

1 files changed, 19 insertions, 0 deletions

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=