Save work on documentation.

Author: michaelrsweet

cups/ipp-file.c

@@ -310,11 +310,13 @@ ippFileGetVar(ipp_file_t *file,		// I - IPP data file
 
 
 //
-// 'ippFileNew()' - Create a new IPP data file object for reading or writing.
+// 'ippFileNew()' - Create a new IPP data file object in preparation for reading or writing.
 //
-// This function opens an IPP data file for reading (mode="r") or writing
-// (mode="w").  If the "parent" argument is not `NULL`, all variables from the
-// parent data file are copied to the new file.
+// This function creates a new IPP data file object.  If the "parent" argument
+// is not `NULL`, all variables from the parent data file are copied to the new
+// object.
+//
+// Call the @link ippFileOpen@ function to open the IPP data file.
 //
 
 ipp_file_t *				// O - IPP data file
@@ -343,9 +345,8 @@ ippFileNew(ipp_file_t      *parent,	// I - Parent data file or `NULL` for none
 //
 // 'ippFileOpen()' - Open an IPP data file for reading or writing.
 //
-// This function opens an IPP data file for reading (mode="r") or writing
-// (mode="w").  If the "parent" argument is not `NULL`, all variables from the
-// parent data file are copied to the new file.
+// This function opens the IPP data file specified by the "filename" argument
+// for reading ("mode" is "r") or writing ("mode" is "w").
 //
 
 bool					// O - `true` on success, `false` on error
@@ -389,6 +390,14 @@ ippFileOpen(ipp_file_t *file,		// I - IPP data file
 //
 // 'ippFileRead()' - Read an IPP data file.
 //
+// This function reads tokens from an IPP data file, processes standard
+// directives that define attributes and values, and passes on unknown tokens
+// to the token callback "token_cb" for processing.
+//
+// If the "with_groups" argument is `true` then the "GROUP" directive will be
+// supported for specifying the attribute group(s) associated with any
+// defined attributes.
+//
 
 bool					// O - `true` on success, `false` on error
 ippFileRead(ipp_file_t      *file,	// I - IPP data file

cups/language.c

@@ -75,6 +75,9 @@ static int		cups_message_compare(_cups_message_t *m1, _cups_message_t *m2);
 //
 // 'cupsLangAddStrings()' - Add strings for the specified language.
 //
+// This function adds strings for the specified language.  It is equivalent to
+// calling @link cupsLangFind@ followed by @link cupsLangLoadStrings@.
+//
 
 bool					// O - `true` on success, `false` on failure
 cupsLangAddStrings(
@@ -94,9 +97,12 @@ cupsLangAddStrings(
 //
 // 'cupsLangFind()' - Find a language localization.
 //
+// This function finds the localization information for the specified language
+// or locale name.
+//
 
 cups_lang_t *				// O - Language data
-cupsLangFind(const char *language)	// I - Language or locale name
+cupsLangFind(const char *language)	// I - Language or locale name, `NULL` for the current locale
 {
   char		langname[16];		// Requested language name
   cups_lang_t	*lang;			// Current language...
@@ -134,6 +140,9 @@ cupsLangFind(const char *language)	// I - Language or locale name
 //
 // 'cupsLangFormatString()' - Create a localized formatted string.
 //
+// This function formats a string using the localized version of the "format"
+// string argument, which supports all of the `printf` format specifiers.
+//
 
 const char *				// O - Formatted string
 cupsLangFormatString(
@@ -223,11 +232,21 @@ cupsLangIsRTL(cups_lang_t *lang)	// I - Language
 //
 // 'cupsLangLoadStrings()' - Load a message catalog for a language.
 //
+// This function loads a message catalog for a language.  The catalog must be in
+// the Apple .strings format.  For example, the following translates the strings
+// "Yes", "No", and "Welcome, %s." to French:
+//
+// ```
+// "Yes" = "Oui";
+// "No" = "Non";
+// "Welcome, %s." = "Bievenue, %s.";
+// ```
+//
 
 bool				// O - `true` on success, `false` on failure
 cupsLangLoadStrings(
     cups_lang_t *lang,			// I - Language data
-    const char  *filename,		// I - Filename of `NULL` for none
+    const char  *filename,		// I - Filename or `NULL` for none
     const char  *strings)		// I - Strings or `NULL` for none
 {
   bool		ret = true;		// Return value
@@ -560,7 +579,11 @@ cupsLangLoadStrings(
 
 
 //
-// 'cupsLangSetDirectory()' - Set a directory containing localizations.
+// 'cupsLangSetDirectory()' - Set the directory containing localizations.
+//
+// This function sets the directory where .strings files can be found.  The
+// files are named "LOCALE.string" where "LOCALE" is the locale name, for
+// example "fr" for generic French and "fr-CA" for Canadian French.
 //
 
 void