doc/fcatomic.fncs | 4 +++-
doc/fcconfig.fncs | 21 ++++++++++++++-------
doc/fcconstant.fncs | 8 ++++++--
doc/fcfile.fncs | 28 +++++++++++++++-------------
doc/fcfontset.fncs | 3 ++-
doc/fcinit.fncs | 7 +++++--
doc/fcobjectset.fncs | 3 ++-
doc/fcobjecttype.fncs | 6 ++++--
8 files changed, 51 insertions(+), 29 deletions(-)
New commits:
commit fab44f3cb63dc8bd1285dcbd6ad4f1f468f91daf
Author: Keith Packard <keithp at koto.keithp.com>
Date: Tue Nov 13 14:58:39 2007 -0800
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 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 <test> elements with target=pattern.
+p_pat is used for <test> 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 <test> 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
- at PURPOSE@ scan a font directory
+ at 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
- at PURPOSE@ save a directory cache
+ at 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 *