From b3ea7544f7a32949499b331fb51622569974ad2b Mon Sep 17 00:00:00 2001
From: Patrick McDermott <patrick.mcdermott@libiquity.com>
Date: Thu, 27 Dec 2018 22:28:53 -0500
Subject: ob_get_text_domain(), ob_set_text_domain(): Document

Also add a TODO comment to ob_set_text_domain().
---
diff --git a/lib/locale.sh b/lib/locale.sh
index f168037..8196203 100644
--- a/lib/locale.sh
+++ b/lib/locale.sh
@@ -22,6 +22,11 @@ _OB_INTERNAL_TEXT_DOMAIN="libopkbuild_${LIBOPKBUILD_SHSOVERSION}"
 _OB_TEXT_DOMAIN=
 _OB_LOCALE_PATH="${LOCALEDIR}/%s/LC_MESSAGES/%s.ms"
 
+## @brief Get the current message domain
+## @details \fBob_get_text_domain\fP prints the currently loaded message domain.
+## @return Returns 0 on success or 125 if any arguments are given.
+## @stdout Prints the name of the currently loaded message domain.
+## @pure yes This function has no side effects.
 ob_get_text_domain()
 {
 	if [ ${#} -ne 0 ]; then
@@ -50,6 +55,18 @@ _ob_try_load_messages()
 	return 0
 }
 
+## @brief Set and load the message domain
+## @details \fBob_set_text_domain\fP() sets and loads the message domain for
+##          future \fBob_get_msg\fP() calls.  A message domain is a catalog of
+##          localized messages identified by message IDs.  Each application
+##          should have its own message domain.  libopkbuild also has its own
+##          message domain and temporarily switches to it when needed.
+## @operand text_domain req The message domain to load.
+## @return Returns 0 on success, 1 if the message domain cannot be loaded, or
+##         125 if \fItext_domain\fP is missing.
+## @stderr Prints a warning to stderr if the message domain cannot be loaded.
+## @pure no This function sets an internal global variable and loads a message
+##          catalog that sets numerous message variables.
 ob_set_text_domain()
 {
 	if [ ${#} -eq 1 ]; then
@@ -75,6 +92,9 @@ ob_set_text_domain()
 	if ! _ob_try_load_messages "${LC_MESSAGES%.*}"; then
 		if ! _ob_try_load_messages "${LC_MESSAGES%_*}"; then
 			if ! _ob_try_load_messages "${_OB_DEFAULT_LOCALE}"; then
+				# TODO: Move this warning to the executables.
+				# TODO: And use printf, since ob_warn() will be
+				# internationalized.
 				ob_warn 'Cannot load messages in "%s" domain.' \
 					"${_OB_TEXT_DOMAIN}"
 				return 1
--
cgit v0.9.1