Document several function return values (Bug 13145).

Several functions had no indication of what the return value would be,
mostly these were allocation failure returns.

8 files changed, 51 insertions, 29 deletions

diff --git a/doc/fcatomic.fncs b/doc/fcatomic.fncs
index ae27c68..54ea696 100644
--- a/doc/fcatomic.fncs
+++ b/doc/fcatomic.fncs
@@ -65,7 +65,9 @@ Returns the file refernced by <parameter>atomic</parameter>.
 @TYPE1@         FcAtomic *                      @ARG1@          atomic
 @PURPOSE@	replace original with new
 @DESC@
-Replaces the original file referenced by <parameter>atomic</parameter> with the new file.
+Replaces the original file referenced by <parameter>atomic</parameter> with
+the new file. Returns FcFalse if the file cannot be replaced due to
+permission issues in the filesystem. Otherwise returns FcTrue.
 @@
 
 @RET@           void
diff --git a/doc/fcconfig.fncs b/doc/fcconfig.fncs
index bf4f1dd..468bb77 100644
--- a/doc/fcconfig.fncs
+++ b/doc/fcconfig.fncs
@@ -177,7 +177,8 @@ a call to FcFontList when this interval has passed since the last check.
 @TYPE2@		int%                       	@ARG2@          rescanInterval
 @PURPOSE@	Set config rescan interval
 @DESC@
-Sets the rescan interval; returns FcFalse if an error occurred.
+Sets the rescan interval. Returns FcFalse if the interval cannot be set (due
+to allocation failure). Otherwise returns FcTrue.
 @@
 
 @RET@           FcBool
@@ -186,7 +187,8 @@ Sets the rescan interval; returns FcFalse if an error occurred.
 @TYPE2@		const FcChar8 *			@ARG2@          file
 @PURPOSE@	Add font file to font database
 @DESC@
-Adds an application-specific font to the configuration.
+Adds an application-specific font to the configuration. Returns FcFalse
+if the fonts cannot be added (due to allocation failure). Otherwise returns FcTrue.
 @@
 
 @RET@           FcBool
@@ -196,7 +198,8 @@ Adds an application-specific font to the configuration.
 @PURPOSE@	Add fonts from directory to font database
 @DESC@
 Scans the specified directory for fonts, adding each one found to the
-application-specific set of fonts.
+application-specific set of fonts. Returns FcFalse
+if the fonts cannot be added (due to allocation failure). Otherwise returns FcTrue.
 @@
 
 @RET@           void
@@ -218,7 +221,8 @@ Clears the set of application-specific fonts.
 Performs the sequence of pattern modification operations, if <parameter>kind</parameter> is
 FcMatchPattern, then those tagged as pattern operations are applied, else
 if <parameter>kind</parameter> is FcMatchFont, those tagged as font operations are applied and
-p_pat is used for &lt;test&gt; elements with target=pattern.
+p_pat is used for &lt;test&gt; elements with target=pattern. Returns FcFalse
+if the substitution cannot be performed (due to allocation failure). Otherwise returns FcTrue.
 @@
 
 @RET@           FcBool
@@ -228,7 +232,8 @@ p_pat is used for &lt;test&gt; elements with target=pattern.
 @TYPE3@		FcMatchKind%                    @ARG3@          kind
 @PURPOSE@	Execute substitutions
 @DESC@
-Calls FcConfigSubstituteWithPat setting p_pat to NULL.
+Calls FcConfigSubstituteWithPat setting p_pat to NULL. Returns FcFalse
+if the substitution cannot be performed (due to allocation failure). Otherwise returns FcTrue.
 @@
 
 @RET@           FcPattern *
@@ -318,6 +323,8 @@ FC_CONFIG_DIR environment variable.
 @DESC@
 Walks the configuration in 'file' and constructs the internal representation
 in 'config'.  Any include files referenced from within 'file' will be loaded
-and parsed.  If 'complain' is FcFalse, no warning
-will be displayed if 'file' does not exist.
+and parsed.  If 'complain' is FcFalse, no warning will be displayed if
+'file' does not exist. Error and warning messages will be output to stderr.
+Returns FcFalse if some error occurred while loading the file, either a
+parse error, semantic error or allocation failure. Otherwise returns FcTrue.
 @@
diff --git a/doc/fcconstant.fncs b/doc/fcconstant.fncs
index a09bb39..8fb4e90 100644
--- a/doc/fcconstant.fncs
+++ b/doc/fcconstant.fncs
@@ -27,7 +27,9 @@
 @TYPE2@		int%				@ARG2@		nconsts
 @PURPOSE@	Register symbolic constants
 @DESC@
-Register <parameter>nconsts</parameter> new symbolic constants.
+Register <parameter>nconsts</parameter> new symbolic constants. Returns
+FcFalse if the constants cannot be registered (due to allocation failure).
+Otherwise returns FcTrue.
 @@
 
 @RET@		FcBool
@@ -36,7 +38,9 @@ Register <parameter>nconsts</parameter> new symbolic constants.
 @TYPE2@		int%				@ARG2@		nconsts
 @PURPOSE@	Unregister symbolic constants
 @DESC@
-Unregister <parameter>nconsts</parameter> symbolic constants.
+Unregister <parameter>nconsts</parameter> symbolic constants. Returns
+FcFalse if the specified constants were not registered. Otherwise returns
+FcTrue.
 @@
 
 @RET@		const FcConstant *
diff --git a/doc/fcfile.fncs b/doc/fcfile.fncs
index 4821365..80d7e7f 100644
--- a/doc/fcfile.fncs
+++ b/doc/fcfile.fncs
@@ -41,7 +41,8 @@ policy as well as the current configuration. Internally, fontconfig will
 ignore BDF and PCF fonts which are not in Unicode (or the effectively
 equivalent ISO Latin-1) encoding as those are not usable by Unicode-based
 applications. The configuration can ignore fonts based on filename or
-contents of the font file itself.
+contents of the font file itself. Returns FcFalse if any of the fonts cannot be
+added (due to allocation failure). Otherwise returns FcTrue.
 @@
 
 @RET@		FcBool
@@ -61,15 +62,14 @@ returns FcFalse.
 @TYPE4@		FcBlanks *			@ARG4@		blanks	
 @TYPE5@		const FcChar8 *			@ARG5@		dir	
 @TYPE6@		FcBool% 				@ARG6@		force	
-@PURPOSE@	scan a font directory
+@PURPOSE@	DEPRECATED: formerly used to scan a font directory
 @DESC@
-Scans an entire directory and adds all fonts found to
-<parameter>set</parameter>.  If <parameter>force</parameter> is FcTrue, then
-the directory and all files within it are scanned even if information is
-present in the per-directory cache file or <parameter>cache</parameter>.  Any
-subdirectories found are added to <parameter>dirs</parameter>. See the
-manual for <function>FcFileScan</function> for a description of how
-fontconfig selects which fonts to include.
+This function does nothing aside from returning FcFalse. It used to scan an
+entire directory and add all fonts found to
+<parameter>set</parameter>.  If <parameter>force</parameter> was FcTrue, then
+the directory and all files within it were scanned even if information was
+present in the per-directory cache file or <parameter>cache</parameter>. Any
+subdirectories found were added to <parameter>dirs</parameter>.
 @@
 
 @RET@		FcBool 	
@@ -77,10 +77,12 @@ fontconfig selects which fonts to include.
 @TYPE1@		FcFontSet *			@ARG1@		set	
 @TYPE2@		FcStrSet *			@ARG2@		dirs	
 @TYPE3@		const FcChar8 *			@ARG3@		dir	
-@PURPOSE@	save a directory cache
+@PURPOSE@	DEPRECATED: formerly used to save a directory cache
 @DESC@
-Creates the per-directory cache file for <parameter>dir</parameter> and
-populates it with the fonts in <parameter>set</parameter> and subdirectories
-in <parameter>dirs</parameter>.
+This function now does nothing aside from returning FcFalse. It used to creates the
+per-directory cache file for <parameter>dir</parameter> and populates it
+with the fonts in <parameter>set</parameter> and subdirectories in
+<parameter>dirs</parameter>. All of this functionality is now automatically
+managed by FcDirCacheLoad and FcDirCacheRead.
 @@
 
diff --git a/doc/fcfontset.fncs b/doc/fcfontset.fncs
index bcf4bd3..e9e1701 100644
--- a/doc/fcfontset.fncs
+++ b/doc/fcfontset.fncs
@@ -45,7 +45,8 @@ well.
 @PURPOSE@	Add to a font set
 @DESC@
 Adds a pattern to a font set.  Note that the pattern is not copied before
-being inserted into the set.
+being inserted into the set. Returns FcFalse if the pattern cannot be
+inserted into the set (due to allocation failure). Otherwise returns FcTrue.
 @@
 
 @RET@		FcFontSet *
diff --git a/doc/fcinit.fncs b/doc/fcinit.fncs
index 7b56282..13e4604 100644
--- a/doc/fcinit.fncs
+++ b/doc/fcinit.fncs
@@ -75,7 +75,9 @@ Returns the version number of the library.
 @PURPOSE@	re-initialize library
 @DESC@
 Forces the default configuration file to be reloaded and resets the default
-configuration.
+configuration. Returns FcFalse if the configuration cannot be reloaded (due
+to config file errors, allocation failures or other issues) and leaves the
+existing configuration unchanged. Otherwise returns FcTrue.
 @@
 
 @RET@           FcBool       
@@ -85,5 +87,6 @@ configuration.
 @DESC@
 Checks the rescan interval in the default configuration, checking the
 configuration if the interval has passed and reloading the configuration if
-when any changes are detected.
+when any changes are detected. Returns FcFalse if the configuration cannot
+be reloaded (see FcInitReinitialize). Otherwise returns FcTrue.
 @@
diff --git a/doc/fcobjectset.fncs b/doc/fcobjectset.fncs
index 4b0629e..ce1ecae 100644
--- a/doc/fcobjectset.fncs
+++ b/doc/fcobjectset.fncs
@@ -35,7 +35,8 @@ Creates an empty set.
 @TYPE2@		const char *			@ARG2@		object
 @PURPOSE@	Add to an object set
 @DESC@
-Adds a proprety name to the set.
+Adds a proprety name to the set. Returns FcFalse if the property name cannot be
+inserted into the set (due to allocation failure). Otherwise returns FcTrue.
 @@
 
 @RET@		void
diff --git a/doc/fcobjecttype.fncs b/doc/fcobjecttype.fncs
index f472cba..8325dd6 100644
--- a/doc/fcobjecttype.fncs
+++ b/doc/fcobjecttype.fncs
@@ -27,7 +27,9 @@
 @TYPE2@		int%				@ARG2@		ntype
 @PURPOSE@	Register object types
 @DESC@
-Register <parameter>ntype</parameter> new object types.
+Register <parameter>ntype</parameter> new object types. Returns FcFalse if
+some of the names cannot be
+registered (due to allocation failure). Otherwise returns FcTrue.
 @@
 
 @RET@		FcBool
@@ -36,7 +38,7 @@ Register <parameter>ntype</parameter> new object types.
 @TYPE2@		int% 				@ARG2@		ntype
 @PURPOSE@	Unregister object types
 @DESC@
-Unregister <parameter>ntype</parameter> object types.
+Unregister <parameter>ntype</parameter> object types. Returns FcTrue.
 @@
 
 @RET@		const FcObjectType *