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.
This commit is contained in:
Keith Packard 2007-11-13 14:58:39 -08:00
parent ed7955a58f
commit fab44f3cb6
8 changed files with 51 additions and 29 deletions

View File

@ -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

View File

@ -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.
@@

View File

@ -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 *

View File

@ -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
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 are added to <parameter>dirs</parameter>. See the
manual for <function>FcFileScan</function> for a description of how
fontconfig selects which fonts to include.
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.
@@

View File

@ -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 *

View File

@ -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.
@@

View File

@ -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

View File

@ -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 *