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.

diff --git a/doc/fcatomic.fncs b/doc/fcatomic.fncs
index ae27c687f5e2d5be3beba4a8bd4f842ba01eb02e..54ea6961fd5f9bdc326068f4d5dcfe0e501eba17 100644 (file)
--- 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 bf4f1dd5654f884f070dfe3ab7f61336cbe44b03..468bb77b833ea97a8c89799fccf60abd380c37a9 100644 (file)
--- 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 a09bb39211b838d155fef4e5821c72827c5bb6b2..8fb4e90107c6058ea9667e17d6844cd3c80f31f4 100644 (file)
--- 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 48213655457f743b68ddbb22dc7eec724d9bd285..80d7e7f7270876488f36b766c301e50f9e7f5bf9 100644 (file)
--- 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 bcf4bd3e7fa979fd0e40b119d9f999c9807adf99..e9e170143e5f5c1877ad8a5d8b1c42782070b0f9 100644 (file)
--- 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 7b56282548f74166378b24936e17c044b12ae585..13e4604e5917d037779a48f5e316a82d0c1bb633 100644 (file)
--- 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 4b0629e284ab49f84a4ba6fd0c481bbeb4795ce5..ce1ecaec27c4cbf4f5b59691accb915c6e26559b 100644 (file)
--- 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 f472cbae049d572bc7282103853aeed505b46881..8325dd64eda14edc8496c5fdccfa8acf2c007dd5 100644 (file)
--- 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 *