From fab44f3cb63dc8bd1285dcbd6ad4f1f468f91daf Mon Sep 17 00:00:00 2001 From: Keith Packard Date: Tue, 13 Nov 2007 14:58:39 -0800 Subject: [PATCH] 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. --- 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(-) 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 atomic. @TYPE1@ FcAtomic * @ARG1@ atomic @PURPOSE@ replace original with new @DESC@ -Replaces the original file referenced by atomic with the new file. +Replaces the original file referenced by atomic 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 kind is FcMatchPattern, then those tagged as pattern operations are applied, else if kind 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 nconsts new symbolic constants. +Register nconsts 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 nconsts new symbolic constants. @TYPE2@ int% @ARG2@ nconsts @PURPOSE@ Unregister symbolic constants @DESC@ -Unregister nconsts symbolic constants. +Unregister nconsts 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 -set. If force is FcTrue, then -the directory and all files within it are scanned even if information is -present in the per-directory cache file or cache. Any -subdirectories found are added to dirs. See the -manual for FcFileScan 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 +set. If force was FcTrue, then +the directory and all files within it were scanned even if information was +present in the per-directory cache file or cache. Any +subdirectories found were added to dirs. @@ @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 dir and -populates it with the fonts in set and subdirectories -in dirs. +This function now does nothing aside from returning FcFalse. It used to creates the +per-directory cache file for dir and populates it +with the fonts in set and subdirectories in +dirs. 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 ntype new object types. +Register ntype 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 ntype new object types. @TYPE2@ int% @ARG2@ ntype @PURPOSE@ Unregister object types @DESC@ -Unregister ntype object types. +Unregister ntype object types. Returns FcTrue. @@ @RET@ const FcObjectType * -- 2.39.2