Commit 4d12e0d6 authored by Matthias Clasen's avatar Matthias Clasen

Docs: Don't use the emphasis tag

Most of the time, the text read just as well without the extra
boldness.
parent 64eface4
......@@ -105,12 +105,11 @@
* <para id="io-priority"><indexterm><primary>I/O
* priority</primary></indexterm> Many I/O-related asynchronous
* operations have a priority parameter, which is used in certain
* cases to determine the order in which operations are executed. They
* are <emphasis>not</emphasis> used to determine system-wide I/O
* scheduling. Priorities are integers, with lower numbers indicating
* higher priority. It is recommended to choose priorities between
* %G_PRIORITY_LOW and %G_PRIORITY_HIGH, with %G_PRIORITY_DEFAULT as a
* default. </para>
* cases to determine the order in which operations are executed.
* They are not used to determine system-wide I/O scheduling.
* Priorities are integers, with lower numbers indicating higher priority.
* It is recommended to choose priorities between %G_PRIORITY_LOW and
* %G_PRIORITY_HIGH, with %G_PRIORITY_DEFAULT as a default.</para>
**/
typedef GAsyncResultIface GAsyncResultInterface;
......
......@@ -90,16 +90,14 @@ g_cancellable_class_init (GCancellableClass *klass)
*
* Note that disconnecting from this signal (or any signal) in a
* multi-threaded program is prone to race conditions. For instance
* it is possible that a signal handler may be invoked even
* <emphasis>after</emphasis> a call to
* g_signal_handler_disconnect() for that handler has already
* returned.
* it is possible that a signal handler may be invoked even after
* a call to g_signal_handler_disconnect() for that handler has
* already returned.
*
* There is also a problem when cancellation happen
* right before connecting to the signal. If this happens the
* signal will unexpectedly not be emitted, and checking before
* connecting to the signal leaves a race condition where this is
* still happening.
* There is also a problem when cancellation happens right before
* connecting to the signal. If this happens the signal will
* unexpectedly not be emitted, and checking before connecting to
* the signal leaves a race condition where this is still happening.
*
* In order to make it safe and easy to connect handlers there
* are two helper functions: g_cancellable_connect() and
......
......@@ -1303,8 +1303,8 @@ g_data_input_stream_read_until_finish (GDataInputStream *stream,
* occurrence of any of the stop characters.
*
* In contrast to g_data_input_stream_read_until(), this function
* does <emphasis>not</emphasis> consume the stop character. You have
* to use g_data_input_stream_read_byte() to get it before calling
* does not consume the stop character. You have to use
* g_data_input_stream_read_byte() to get it before calling
* g_data_input_stream_read_upto() again.
*
* Note that @stop_chars may contain '\0' if @stop_chars_len is
......@@ -1397,8 +1397,8 @@ g_data_input_stream_read_upto (GDataInputStream *stream,
* It is an error to have two outstanding calls to this function.
*
* In contrast to g_data_input_stream_read_until(), this function
* does <emphasis>not</emphasis> consume the stop character. You have
* to use g_data_input_stream_read_byte() to get it before calling
* does not consume the stop character. You have to use
* g_data_input_stream_read_byte() to get it before calling
* g_data_input_stream_read_upto() again.
*
* Note that @stop_chars may contain '\0' if @stop_chars_len is
......@@ -1437,9 +1437,9 @@ g_data_input_stream_read_upto_async (GDataInputStream *stream,
* Finish an asynchronous call started by
* g_data_input_stream_read_upto_async().
*
* Note that this function does <emphasis>not</emphasis> consume the
* stop character. You have to use g_data_input_stream_read_byte() to
* get it before calling g_data_input_stream_read_upto_async() again.
* Note that this function does not consume the stop character. You
* have to use g_data_input_stream_read_byte() to get it before calling
* g_data_input_stream_read_upto_async() again.
*
* Returns: (transfer full): a string with the data that was read
* before encountering any of the stop characters. Set @length to
......
......@@ -5110,10 +5110,9 @@ obj_message_func (GDBusConnection *connection,
*
* GDBus automatically implements the standard D-Bus interfaces
* org.freedesktop.DBus.Properties, org.freedesktop.DBus.Introspectable
* and org.freedesktop.Peer, so you don't have to implement those for
* the objects you export. You <emphasis>can</emphasis> implement
* org.freedesktop.DBus.Properties yourself, e.g. to handle getting
* and setting of properties asynchronously.
* and org.freedesktop.Peer, so you don't have to implement those for the
* objects you export. You can implement org.freedesktop.DBus.Properties
* yourself, e.g. to handle getting and setting of properties asynchronously.
*
* Note that the reference count on @interface_info will be
* incremented by 1 (unless allocated statically, e.g. if the
......
......@@ -580,7 +580,7 @@ g_dbus_method_invocation_return_value_with_unix_fd_list (GDBusMethodInvocation *
* applications using GDBus.
*
* If you are writing an application intended to be portable,
* <emphasis>always</emphasis> register errors with g_dbus_error_register_error()
* always register errors with g_dbus_error_register_error()
* or use g_dbus_method_invocation_return_dbus_error().
*
* This method will free @invocation, you cannot use it afterwards.
......
......@@ -91,13 +91,12 @@
*
* Ultimately, #GDBusObjectManagerClient is used to obtain #GDBusProxy
* instances. All signals (including the
* <literal>org.freedesktop.DBus.Properties::PropertiesChanged</literal>
* signal) delivered to #GDBusProxy instances are guaranteed to
* originate from the name owner. This guarantee along with the
* behavior described above, means that certain race conditions
* including the <emphasis><quote>half the proxy is from the old owner
* and the other half is from the new owner</quote></emphasis> problem
* cannot happen.
* org.freedesktop.DBus.Properties::PropertiesChanged signal)
* delivered to #GDBusProxy instances are guaranteed to originate
* from the name owner. This guarantee along with the behavior
* described above, means that certain race conditions including the
* "half the proxy is from the old owner and the other half is from
* the new owner" problem cannot happen.
*
* To avoid having the application connect to signals on the returned
* #GDBusObjectProxy and #GDBusProxy objects, the
......
......@@ -361,7 +361,7 @@ g_dbus_proxy_class_init (GDBusProxyClass *klass)
* Ensure that interactions with this proxy conform to the given
* interface. This is mainly to ensure that malformed data received
* from the other peer is ignored. The given #GDBusInterfaceInfo is
* said to be the <emphasis>expected interface</emphasis>.
* said to be the "expected interface".
*
* The checks performed are:
* <itemizedlist>
......
......@@ -562,10 +562,9 @@ g_dbus_gvariant_to_gvalue (GVariant *value,
* #G_TYPE_BOXED derived-types) not in the table above.
*
* Note that if @gvalue is of type #G_TYPE_VARIANT and its value is
* %NULL, the <emphasis>empty</emphasis> #GVariant instance (never
* %NULL) for @type is returned (e.g. 0 for scalar types, the empty
* string for string types, <literal>'/'</literal> for object path
* types, the empty array for any array type and so on).
* %NULL, the empty #GVariant instance (never %NULL) for @type is
* returned (e.g. 0 for scalar types, the empty string for string types,
* '/' for object path types, the empty array for any array type and so on).
*
* See the g_dbus_gvariant_to_gvalue() function for how to convert a
* #GVariant to a #GValue.
......
......@@ -41,11 +41,10 @@
* want your code to work under both UNIX and Windows, you will need
* to take these differences into account.
*
* Also, under glibc, certain non-portable functions are only visible
* in the headers if you define <literal>_GNU_SOURCE</literal> before
* including them. Note that this symbol must be defined before
* including <emphasis>any</emphasis> headers, or it may not take
* effect.
* Also, under GNU libc, certain non-portable functions are only visible
* in the headers if you define %_GNU_SOURCE before including them. Note
* that this symbol must be defined before including any headers, or it
* may not take effect.
*/
/**
......
......@@ -262,10 +262,9 @@ g_network_monitor_default_init (GNetworkMonitorInterface *iface)
* connected to a functioning router that has lost its own upstream
* connectivity. Some hosts might only be accessible when a VPN is
* active. Other hosts might only be accessible when the VPN is
* <emphasis>not</emphasis> active. Thus, it is best to use
* g_network_monitor_can_reach() or
* g_network_monitor_can_reach_async() to test for reachability on a
* host-by-host basis. (On the other hand, when the property is
* not active. Thus, it is best to use g_network_monitor_can_reach()
* or g_network_monitor_can_reach_async() to test for reachability
* on a host-by-host basis. (On the other hand, when the property is
* %FALSE, the application can reasonably expect that no remote
* hosts at all are reachable, and should indicate this to the user
* in its UI.)
......
......@@ -399,13 +399,12 @@ g_output_stream_vprintf (GOutputStream *stream,
* bindings or in other cases where the refcounted nature of #GBytes
* is helpful over a bare pointer interface.
*
* However, note that this function <emphasis>may</emphasis> still
* perform partial writes, just like g_output_stream_write(). If that
* occurs, to continue writing, you will need to create a new #GBytes
* containing just the remaining bytes, using
* g_bytes_new_from_bytes(). Passing the same #GBytes instance
* multiple times potentially can result in duplicated data in the
* output stream.
* However, note that this function may still perform partial writes,
* just like g_output_stream_write(). If that occurs, to continue
* writing, you will need to create a new #GBytes containing just the
* remaining bytes, using g_bytes_new_from_bytes(). Passing the same
* #GBytes instance multiple times potentially can result in duplicated
* data in the output stream.
*
* Return value: Number of bytes written, or -1 on error
**/
......@@ -897,13 +896,12 @@ write_bytes_callback (GObject *stream,
* takes a #GBytes as input. Due to the refcounted nature of #GBytes,
* this allows the stream to avoid taking a copy of the data.
*
* However, note that this function <emphasis>may</emphasis> still
* perform partial writes, just like g_output_stream_write_async().
* If that occurs, to continue writing, you will need to create a new
* #GBytes containing just the remaining bytes, using
* g_bytes_new_from_bytes(). Passing the same #GBytes instance
* multiple times potentially can result in duplicated data in the
* output stream.
* However, note that this function may still perform partial writes,
* just like g_output_stream_write_async(). If that occurs, to continue
* writing, you will need to create a new #GBytes containing just the
* remaining bytes, using g_bytes_new_from_bytes(). Passing the same
* #GBytes instance multiple times potentially can result in duplicated
* data in the output stream.
*
* For the synchronous, blocking version of this function, see
* g_output_stream_write_bytes().
......
......@@ -595,9 +595,8 @@ g_resolver_get_service_rrname (const char *service,
* Synchronously performs a DNS SRV lookup for the given @service and
* @protocol in the given @domain and returns an array of #GSrvTarget.
* @domain may be an ASCII-only or UTF-8 hostname. Note also that the
* @service and @protocol arguments <emphasis>do not</emphasis>
* include the leading underscore that appears in the actual DNS
* entry.
* @service and @protocol arguments do not include the leading underscore
* that appears in the actual DNS entry.
*
* On success, g_resolver_lookup_service() will return a #GList of
* #GSrvTarget, sorted in order of preference. (That is, you should
......
......@@ -2850,8 +2850,7 @@ g_settings_binding_writable_changed (GSettings *settings,
*
* When the @inverted argument is %TRUE, the binding inverts the
* value as it passes from the setting to the object, i.e. @property
* will be set to %TRUE if the key is <emphasis>not</emphasis>
* writable.
* will be set to %TRUE if the key is not writable.
*
* Note that the lifecycle of the binding is tied to the object,
* and that you can have only one binding per object property.
......
......@@ -1190,8 +1190,8 @@ g_task_return (GTask *task,
* g_task_set_return_on_cancel() for more details.
*
* Other than in that case, @task will be completed when the
* #GTaskThreadFunc returns, <emphasis>not</emphasis> when it calls
* a <literal>g_task_return_</literal> function.
* #GTaskThreadFunc returns, not when it calls a
* <literal>g_task_return_</literal> function.
*
* Since: 2.36
*/
......
......@@ -737,7 +737,7 @@
* p = (void*) 42;
* i = (int) p;
* ]|
* Again, that example was <emphasis>not</emphasis> correct, don't copy it.
* Again, that example was not correct, don't copy it.
* The problem is that on some systems you need to do this:
* |[
* gpointer p;
......@@ -761,9 +761,9 @@
* Stuffs an integer into a pointer type.
*
* Remember, you may not store pointers in integers. This is not portable
* in any way, shape or form. These macros <emphasis>only</emphasis> allow
* storing integers in pointers, and only preserve 32 bits of the
* integer; values outside the range of a 32-bit integer will be mangled.
* in any way, shape or form. These macros only allow storing integers in
* pointers, and only preserve 32 bits of the integer; values outside the
* range of a 32-bit integer will be mangled.
*/
/**
......@@ -774,9 +774,9 @@
* been stored in the pointer with GINT_TO_POINTER().
*
* Remember, you may not store pointers in integers. This is not portable
* in any way, shape or form. These macros <emphasis>only</emphasis> allow
* storing integers in pointers, and only preserve 32 bits of the
* integer; values outside the range of a 32-bit integer will be mangled.
* in any way, shape or form. These macros only allow storing integers in
* pointers, and only preserve 32 bits of the integer; values outside the
* range of a 32-bit integer will be mangled.
*/
/**
......@@ -1679,19 +1679,17 @@
/**
* G_CONST_RETURN:
*
* If <literal>G_DISABLE_CONST_RETURNS</literal> is defined, this macro expands
* to nothing. By default, the macro expands to <literal>const</literal>.
* The macro should be used in place of <literal>const</literal> for
* functions that return a value that should not be modified. The
* purpose of this macro is to allow us to turn on <literal>const</literal>
* for returned constant strings by default, while allowing programmers
* who find that annoying to turn it off. This macro should only be used
* for return values and for <emphasis>out</emphasis> parameters, it doesn't
* make sense for <emphasis>in</emphasis> parameters.
* If %G_DISABLE_CONST_RETURNS is defined, this macro expands
* to nothing. By default, the macro expands to const. The macro
* can be used in place of const for functions that return a value
* that should not be modified. The purpose of this macro is to allow
* us to turn on const for returned constant strings by default, while
* allowing programmers who find that annoying to turn it off. This macro
* should only be used for return values and for "out" parameters, it
* doesn't make sense for "in" parameters.
*
* Deprecated: 2.30: API providers should replace all existing uses with
* <literal>const</literal> and API consumers should adjust their code
* accordingly
* const and API consumers should adjust their code accordingly
*/
/**
......
......@@ -438,7 +438,7 @@ append_locale_variants (GPtrArray *array,
* For example, if @locale is "fr_BE", then the returned list
* is "fr_BE", "fr".
*
* If you need the list of variants for the <emphasis>current locale</emphasis>,
* If you need the list of variants for the current locale,
* use g_get_language_names().
*
* Returns: (transfer full) (array zero-terminated=1) (element-type utf8): a newly
......
......@@ -98,12 +98,11 @@
* that use Glib do the same thing. If you get a file name from
* the file system, for example, from readdir(3) or from g_dir_read_name(),
* and you wish to display the file name to the user, you
* <emphasis>will</emphasis> need to convert it into UTF-8. The
* opposite case is when the user types the name of a file he
* wishes to save: the toolkit will give you that string in
* UTF-8 encoding, and you will need to convert it to the
* character set used for file names before you can create the
* file with open(2) or fopen(3).
* will need to convert it into UTF-8. The opposite case is when the
* user types the name of a file he wishes to save: the toolkit will
* give you that string in UTF-8 encoding, and you will need to convert
* it to the character set used for file names before you can create the
* file with open() or fopen().
* </para>
* <para>
* By default, Glib assumes that file names on disk are in UTF-8
......@@ -157,9 +156,9 @@
* <listitem><para>
* If you need to display a file name, convert it to UTF-8 first by
* using g_filename_to_utf8(). If conversion fails, display a string like
* "<literal>Unknown file name</literal>". <emphasis>Do not</emphasis>
* convert this string back into the encoding used for file names if you
* wish to pass it to the file system; use the original file name instead.
* "Unknown file name". Do not convert this string back into the encoding
* used for file names if you wish to pass it to the file system; use the
* original file name instead.
* For example, the document window of a word processor could display
* "Unknown file name" in its title bar but still let the user save the
* file, as it would keep the raw file name internally. This can happen
......
......@@ -69,7 +69,7 @@
* or ISO timestamps or the like. It extrapolates the current Gregorian
* calendar forward and backward in time; there is no attempt to change
* the calendar to match time periods or locations. #GDate does not store
* time information; it represents a <emphasis>day</emphasis>.
* time information; it represents a day.
*
* The #GDate implementation has several nice features; it is only a
* 64-bit struct, so storing large numbers of dates is very efficient. It
......@@ -87,16 +87,16 @@
* calling g_date_clear(). A cleared date is sane; it's safe to call
* g_date_set_dmy() and the other mutator functions to initialize the
* value of a cleared date. However, a cleared date is initially
* <emphasis>invalid</emphasis>, meaning that it doesn't represent a day
* that exists. It is undefined to call any of the date calculation
* routines on an invalid date. If you obtain a date from a user or other
* invalid, meaning that it doesn't represent a day that exists.
* It is undefined to call any of the date calculation routines on an
* invalid date. If you obtain a date from a user or other
* unpredictable source, you should check its validity with the
* g_date_valid() predicate. g_date_valid() is also used to check for
* errors with g_date_set_parse() and other functions that can
* fail. Dates can be invalidated by calling g_date_clear() again.
*
* <emphasis>It is very important to use the API to access the #GDate
* struct.</emphasis> Often only the day-month-year or only the Julian
* It is very important to use the API to access the #GDate
* struct. Often only the day-month-year or only the Julian
* representation is valid. Sometimes neither is valid. Use the API.
*
* GLib also features #GDateTime which represents a precise time.
......@@ -151,11 +151,11 @@
* GTime:
*
* Simply a replacement for time_t. It has been deprecated
* since it is <emphasis>not</emphasis> equivalent to time_t
* on 64-bit platforms with a 64-bit time_t. Unrelated to #GTimer.
* since it is not equivalent to time_t on 64-bit platforms
* with a 64-bit time_t. Unrelated to #GTimer.
*
* Note that #GTime is defined to always be a 32bit integer,
* unlike time_t which may be 64bit on some systems. Therefore,
* Note that #GTime is defined to always be a 32-bit integer,
* unlike time_t which may be 64-bit on some systems. Therefore,
* #GTime will overflow in the year 2038, and you cannot use the
* address of a #GTime variable as argument to the UNIX time()
* function.
......@@ -183,8 +183,8 @@
/**
* GDateDay:
*
* Integer representing a day of the month; between 1 and
* 31. #G_DATE_BAD_DAY represents an invalid day of the month.
* Integer representing a day of the month; between 1 and 31.
* #G_DATE_BAD_DAY represents an invalid day of the month.
*/
/**
......
......@@ -30,18 +30,18 @@
* GLib provides a standard method of reporting errors from a called
* function to the calling code. (This is the same problem solved by
* exceptions in other languages.) It's important to understand that
* this method is both a <emphasis>data type</emphasis> (the #GError
* object) and a <emphasis>set of rules.</emphasis> If you use #GError
* incorrectly, then your code will not properly interoperate with other
* code that uses #GError, and users of your API will probably get confused.
*
* First and foremost: <emphasis>#GError should only be used to report
* recoverable runtime errors, never to report programming
* errors.</emphasis> If the programmer has screwed up, then you should
* use g_warning(), g_return_if_fail(), g_assert(), g_error(), or some
* similar facility. (Incidentally, remember that the g_error() function
* should <emphasis>only</emphasis> be used for programming errors, it
* should not be used to print any error reportable via #GError.)
* this method is both a data type (the #GError struct) and a set of
* rules. If you use #GError incorrectly, then your code will not
* properly interoperate with other code that uses #GError, and users
* of your API will probably get confused.
*
* First and foremost: #GError should only be used to report recoverable
* runtime errors, never to report programming errors. If the programmer
* has screwed up, then you should use g_warning(), g_return_if_fail(),
* g_assert(), g_error(), or some similar facility. (Incidentally,
* remember that the g_error() function should only be used for
* programming errors, it should not be used to print any error
* reportable via #GError.)
*
* Examples of recoverable runtime errors are "file not found" or
* "failed to parse input." Examples of programming errors are "NULL
......@@ -81,14 +81,13 @@
* }
* ]|
* Note that <literal>err != NULL</literal> in this example is a
* <emphasis>reliable</emphasis> indicator of whether
* g_file_get_contents() failed. Additionally, g_file_get_contents()
* returns a boolean which indicates whether it was successful.
* reliable indicator of whether g_file_get_contents() failed.
* Additionally, g_file_get_contents() returns a boolean which
* indicates whether it was successful.
*
* Because g_file_get_contents() returns %FALSE on failure, if you
* are only interested in whether it failed and don't need to display
* an error message, you can pass %NULL for the <literal>error</literal>
* argument:
* an error message, you can pass %NULL for the @error argument:
* |[
* if (g_file_get_contents ("foo.txt", &amp;contents, NULL, NULL)) /&ast; ignore errors &ast;/
* /&ast; no error occurred &ast;/ ;
......@@ -96,21 +95,19 @@
* /&ast; error &ast;/ ;
* ]|
*
* The #GError object contains three fields: <literal>domain</literal>
* indicates the module the error-reporting function is located in,
* <literal>code</literal> indicates the specific error that occurred,
* and <literal>message</literal> is a user-readable error message with
* The #GError object contains three fields: @domain indicates the module
* the error-reporting function is located in, @code indicates the specific
* error that occurred, and @message is a user-readable error message with
* as many details as possible. Several functions are provided to deal
* with an error received from a called function: g_error_matches()
* returns %TRUE if the error matches a given domain and code,
* g_propagate_error() copies an error into an error location (so the
* calling function will receive it), and g_clear_error() clears an
* error location by freeing the error and resetting the location to
* %NULL. To display an error to the user, simply display
* <literal>error-&gt;message</literal>, perhaps along with additional
* context known only to the calling function (the file being opened,
* or whatever -- though in the g_file_get_contents() case,
* <literal>error-&gt;message</literal> already contains a filename).
* %NULL. To display an error to the user, simply display the @message,
* perhaps along with additional context known only to the calling
* function (the file being opened, or whatever - though in the
* g_file_get_contents() case, the @message already contains a filename).
*
* When implementing a function that can report errors, the basic
* tool is g_set_error(). Typically, if a fatal error occurs you
......@@ -209,10 +206,10 @@
* }
* }
* ]|
* <literal>tmp_error</literal> should be checked immediately after
* sub_function_that_can_fail(), and either cleared or propagated
* upward. The rule is: <emphasis>after each error, you must either
* handle the error, or return it to the calling function</emphasis>.
* @tmp_error should be checked immediately after sub_function_that_can_fail(),
* and either cleared or propagated upward. The rule is: after each error,
* you must either handle the error, or return it to the calling function.
*
* Note that passing %NULL for the error location is the equivalent
* of handling an error by always doing nothing about it. So the
* following code is fine, assuming errors in sub_function_that_can_fail()
......@@ -238,11 +235,11 @@
* }
* ]|
*
* Note that passing %NULL for the error location
* <emphasis>ignores</emphasis> errors; it's equivalent to
* Note that passing %NULL for the error location ignores errors; it's
* equivalent to
* <literal>try { sub_function_that_can_fail (); } catch (...) {}</literal>
* in C++. It does <emphasis>not</emphasis> mean to leave errors
* unhandled; it means to handle them by doing nothing.
* in C++. It does not mean to leave errors unhandled; it means to
* handle them by doing nothing.
*
* Error domains and codes are conventionally named as follows:
* <itemizedlist>
......@@ -305,12 +302,11 @@
* not be affected by whether the caller wants to get a #GError.
* </para></listitem>
* <listitem><para>
* If a #GError is reported, then your function by definition
* <emphasis>had a fatal failure and did not complete whatever
* it was supposed to do</emphasis>. If the failure was not fatal,
* then you handled it and you should not report it. If it was fatal,
* then you must report it and discontinue whatever you were doing
* immediately.
* If a #GError is reported, then your function by definition had a
* fatal failure and did not complete whatever it was supposed to do.
* If the failure was not fatal, then you handled it and you should not
* report it. If it was fatal, then you must report it and discontinue
* whatever you were doing immediately.
* </para></listitem>
* <listitem><para>
* If a #GError is reported, out parameters are not guaranteed to
......@@ -331,7 +327,7 @@
* <listitem><para>
* By convention, if you return a boolean value indicating success
* then %TRUE means success and %FALSE means failure. If %FALSE is
* returned, the error <emphasis>must</emphasis> be set to a non-%NULL
* returned, the error must be set to a non-%NULL
* value.
* </para></listitem>
* <listitem><para>
......@@ -668,16 +664,13 @@ g_error_add_prefix (gchar **string,
* @format: printf()-style format string
* @...: arguments to @format
*
* Formats a string according to @format and
* prefix it to an existing error message. If
* @err is %NULL (ie: no error variable) then do
* Formats a string according to @format and prefix it to an existing
* error message. If @err is %NULL (ie: no error variable) then do
* nothing.
*
* If *@err is %NULL (ie: an error variable is
* present but there is no error condition) then
* also do nothing. Whether or not it makes
* sense to take advantage of this feature is up
* to you.
* If *@err is %NULL (ie: an error variable is present but there is no
* error condition) then also do nothing. Whether or not it makes sense
* to take advantage of this feature is up to you.
*
* Since: 2.16
*/
......@@ -703,9 +696,8 @@ g_prefix_error (GError **err,
* @format: printf()-style format string
* @...: arguments to @format
*
* If @dest is %NULL, free @src; otherwise,
* moves @src into *@dest. *@dest must be %NULL.
* After the move, add a prefix as with
* If @dest is %NULL, free @src; otherwise, moves @src into *@dest.
* *@dest must be %NULL. After the move, add a prefix as with
* g_prefix_error().
*
* Since: 2.16
......
......@@ -472,8 +472,8 @@ g_dngettext (const gchar *domain,
*
* In order to use these macros in an application, you must include
* <filename>glib/gi18n.h</filename>. For use in a library, you must include
* <filename>glib/gi18n-lib.h</filename> <emphasis>after</emphasis> defining
* the GETTEXT_PACKAGE macro suitably for your library:
* <filename>glib/gi18n-lib.h</filename> after defining the %GETTEXT_PACKAGE
* macro suitably for your library:
* |[
* &num;define GETTEXT_PACKAGE "gtk20"
* &num;include &lt;glib/gi18n-lib.h&gt;
......
......@@ -1317,8 +1317,7 @@ g_io_channel_get_buffered (GIOChannel *channel)
* %G_CONVERT_ERROR_ILLEGAL_SEQUENCE.
* Returning one of these statuses from g_io_channel_read_line(),
* g_io_channel_read_line_string(), or g_io_channel_read_to_end()
* does <emphasis>not</emphasis> guarantee that the encoding can
* be changed.
* does not guarantee that the encoding can be changed.
* </para></listitem>
* </itemizedlist>
* Channels which do not meet one of the above conditions cannot call
......
......@@ -688,10 +688,9 @@ static GPrivate thread_context_stack = G_PRIVATE_INIT (free_context_stack);
* started in this thread to run under @context and deliver their
* results to its main loop, rather than running under the global
* default context in the main thread. Note that calling this function
* changes the context returned by
* g_main_context_get_thread_default(), <emphasis>not</emphasis> the
* one returned by g_main_context_default(), so it does not affect the
* context used by functions like g_idle_add().
* changes the context returned by g_main_context_get_thread_default(),
* not the one returned by g_main_context_default(), so it does not affect
* the context used by functions like g_idle_add().
*
* Normally you would call this function shortly after creating a new
* thread, passing it a #GMainContext which will be run by a
......
......@@ -493,13 +493,17 @@ g_mem_is_system_malloc (void)
* g_mem_set_vtable:
* @vtable: table of memory allocation routines.
*
* Sets the #GMemVTable to use for memory allocation. You can use this to provide
* custom memory allocation routines. <emphasis>This function must be called
* before using any other GLib functions.</emphasis> The @vtable only needs to
* provide malloc(), realloc(), and free() functions; GLib can provide default
* implementations of the others. The malloc() and realloc() implementations
* should return %NULL on failure, GLib will handle error-checking for you.
* @vtable is copied, so need not persist after this function has been called.
* Sets the #GMemVTable to use for memory allocation. You can use this
* to provide custom memory allocation routines.
*
* The @vtable only needs to provide malloc(), realloc(), and free()
* functions; GLib can provide default implementations of the others.
* The malloc() and realloc() implementations should return %NULL on
* failure, GLib will handle error-checking for you. @vtable is copied,
* so need not persist after this function has been called.
*
* Note that this function must be called before using any other GLib
* functions.
*/
void
g_mem_set_vtable (GMemVTable *vtable)
......
......@@ -553,8 +553,7 @@ g_log_set_fatal_mask (const gchar *log_domain,
* </example>
*
* <example>
* <title>Adding a log handler for <emphasis>all</emphasis> messages from
* GLib</title>
* <title>Adding a log handler for all messages from GLib</title>
* <programlisting>
* g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL
* | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
......
......@@ -2199,11 +2199,11 @@ g_option_group_new (const gchar *name,
* g_option_group_free:
* @group: a #GOptionGroup
*
* Frees a #GOptionGroup. Note that you must <emphasis>not</emphasis>
* free groups which have been added to a #GOptionContext.
* Frees a #GOptionGroup. Note that you must not free groups
* which have been added to a #GOptionContext.
*
* Since: 2.6
**/
*/
void
g_option_group_free (GOptionGroup *group)
{
......
......@@ -38,11 +38,9 @@
* semantics as the standard glob() function: '*' matches an arbitrary,
* possibly empty, string, '?' matches an arbitrary character.
*
* Note that in contrast to glob(), the '/' character
* <emphasis>can</emphasis> be matched by the wildcards, there are no
* '[...]' character ranges and '*' and '?' can
* <emphasis>not</emphasis> be escaped to include them literally in a
* pattern.
* Note that in contrast to glob(), the '/' character can be matched by
* the wildcards, there are no '[...]' character ranges and '*' and '?' can
* not be escaped to include them literally in a pattern.
*
* When multiple strings must be matched against the same pattern, it
* is better to compile the pattern to a #GPatternSpec using
......@@ -162,7 +160,7 @@ g_pattern_ph_match (const gchar *match_pattern,
* g_pattern_match:
* @pspec: a #GPatternSpec
* @string_length: the length of @string (in bytes, i.e. strlen(),
* <emphasis>not</emphasis> g_utf8_strlen())
* not g_utf8_strlen())
* @string: the UTF-8 encoded string to match
* @string_reversed: (allow-none): the reverse of @string or %NULL
*
......@@ -180,10 +178,9 @@ g_pattern_ph_match (const gchar *match_pattern,
* constructions thereof in the various calls to g_pattern_match().
*
* Note also that the reverse of a UTF-8 encoded string can in general
* <emphasis>not</emphasis> be obtained by g_strreverse(). This works
* only if the string doesn't contain any multibyte characters. GLib
* offers the g_utf8_strreverse() function to reverse UTF-8 encoded
* strings.
* not be obtained by g_strreverse(). This works only if the string
* does not contain any multibyte characters. GLib offers the
* g_utf8_strreverse() function to reverse UTF-8 encoded strings.
*
* Returns: %TRUE if @string matches @pspec
**/
......
......@@ -57,7 +57,7 @@ static gint quark_block_offset = 0;
* SECTION:quarks
* @title: Quarks
* @short_description: a 2-way association between a string and a
* unique integer identifier
* unique integer identifier
*
* Quarks are associations between strings and integer identifiers.
* Given either the string or the #GQuark identifier it is possible to
......@@ -82,14 +82,14 @@ static gint quark_block_offset = 0;
* representation for a string. One important advantage of interned
* strings is that they can be compared for equality by a simple
* pointer comparison, rather than using strcmp().
**/
*/
/**
* GQuark:
*
* A GQuark is a non-zero integer which uniquely identifies a
* particular string. A GQuark value of zero is associated to %NULL.
**/
*/
/**
* G_DEFINE_QUARK:
......@@ -99,24 +99,26 @@ static gint quark_block_offset = 0;
* A convenience macro which defines a function returning the
* #GQuark for the name @QN. The function will be named
* @q_n<!-- -->_quark().
* Note that the quark name will be stringified automatically in the
* macro, so you shouldn't use double quotes.
*
* Note that the quark name will be stringified automatically
* in the macro, so you shouldn't use double quotes.
*
* Since: 2.34
*/
/**
* g_quark_try_string:
* @string: (allow-none): a string.
* @Returns: the #GQuark associated with the string, or 0 if @string is
* %NULL or there is no #GQuark associated with it.
* @string: (allow-none): a string
*
* Gets the #GQuark associated with the given string, or 0 if string is
* %NULL or it has no associated #GQuark.
*
* If you want the GQuark to be created if it doesn't already exist,
* use g_quark_from_string() or g_quark_from_static_string().
**/
*
* Returns: the #GQuark associated with the string, or 0 if @string is
* %NULL or there is no #GQuark associated with it
*/
GQuark
g_quark_try_string (const gchar *string)