From 0e900ee44958b67c64a4e38a98601bf3d7a378a4 Mon Sep 17 00:00:00 2001 From: Patrick McDermott Date: Fri, 28 Dec 2018 22:24:47 -0500 Subject: ob_parse_changelog(): Finish documentation --- 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 +## . 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= -- cgit v0.9.1