ob_parse_changelog(): Finish documentation

1 files changed, 20 insertions, 1 deletions

diff --git a/lib/changelog.sh b/lib/changelog.sh
index 35f7c69..81c5ba8 100644
--- a/lib/changelog.sh
+++ b/lib/changelog.sh
@@ -64,9 +64,28 @@ _ob_get_changelog_expect_str()
 }
 
 ## @brief Parse a changelog file
+## @details \fBob_parse_changelog\fP parses a \fIchangelog\fP file, formatted as
+##          specified at
+##          <http://specs.proteanos.com/spf-2.0/metadata.html#changelog>.  For
+##          each version entry, \fBob_parse_changelog\fP calls \fIentry_cb\fP
+##          after setting \fIOB_CHANGELOG_SOURCE\fP to the source package name,
+##          \fIOB_CHANGELOG_VERSION\fP to the source package version,
+##          \fIOB_CHANGELOG_DISTRIBUTION\fP to the list of distributions into
+##          which the package should be installed, \fIOB_CHANGELOG_CHANGES\fP to
+##          the formatted heading (source package name, source package version,
+##          and distributions list) and change details,
+##          \fIOB_CHANGELOG_MAINTAINER\fP to the name and e-mail address of the
+##          package maintainer, and \fPOB_CHANGELOG_DATE\fP to the date of
+##          packaging.  \fBob_parse_changelog\fP stops parsing either at the end
+##          of the \fIchangelog\fP file or when \fIentry_cb\fP returns non-zero.
 ## @operand file     req The file to parse, or "-" for standard input.
 ## @operand entry_cb req Callback to run for each entry.
-## @return Returns 0.
+## @return Returns 0 after parsing, or 125 on missing arguments.
+## @stderr Prints error messages on parse errors.
+## @pure maybe This function sets global variables, but they're only intended
+##             for use by \fIentry_cb\fP, which is called during the lifetime of
+##             this function.  Whether this function is subshell-safe in
+##             practice depends on whether \fIentry_cb\fP is subshell-safe.
 ob_parse_changelog()
 {
 	local file=