AuroraMiddleware/gtk2
1
0
Fork 0
forked from AuroraMiddleware/gtk
Code Issues Pull Requests Projects Releases Wiki Activity

Docs: Don't use note elements

Browse Source 
In most cases, the text itself makes the message clear enough.
This commit is contained in:
Matthias Clasen 2014-02-02 01:22:14 -05:00
parent 30cc1512e6
commit 245c385ae7
21 changed files with 61 additions and 110 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
gdk/gdkkeys.c
View File

@ -495,14 +495,13 @@ gdk_keymap_lookup_key (GdkKeymap *keymap,
* @state. For convenience, #GdkEventKey already contains the translated
* keyval, so this function isn't as useful as you might think.
*
* <note><para>
* @consumed_modifiers gives modifiers that should be masked out
* from @state when comparing this key press to a hot key. For
* instance, on a US keyboard, the <literal>plus</literal>
* symbol is shifted, so when comparing a key press to a
* <literal>&lt;Control&gt;plus</literal> accelerator &lt;Shift&gt; should
* be masked out.
* </para>
*
* |[<!-- language="C" -->
* /&ast; We want to ignore irrelevant modifiers like ScrollLock &ast;/;
* #define ALL_ACCELS_MASK (GDK_CONTROL_MASK | GDK_SHIFT_MASK | GDK_MOD1_MASK)
@ -513,18 +512,18 @@ gdk_keymap_lookup_key (GdkKeymap *keymap,
* (event->state & ~consumed & ALL_ACCELS_MASK) == GDK_CONTROL_MASK)
* /&ast; Control was pressed &ast;/
* ]|
* <para>
*
* An older interpretation @consumed_modifiers was that it contained
* all modifiers that might affect the translation of the key;
* this allowed accelerators to be stored with irrelevant consumed
* modifiers, by doing:</para>
* modifiers, by doing:
* |[<!-- language="C" -->
* /&ast; XXX Don't do this XXX &ast;/
* if (keyval == accel_keyval &&
* (event->state & ~consumed & ALL_ACCELS_MASK) == (accel_mods & ~consumed))
* /&ast; Accelerator was pressed &ast;/
* ]|
* <para>
*
* However, this did not work if multi-modifier combinations were
* used in the keymap, since, for instance, <literal>&lt;Control&gt;</literal>
* would be masked out even if only <literal>&lt;Control&gt;&lt;Alt&gt;</literal>
@ -536,7 +535,6 @@ gdk_keymap_lookup_key (GdkKeymap *keymap,
* accelerators, you should always store them with consumed modifiers
* removed. Store <literal>&lt;Control&gt;plus</literal>,
* not <literal>&lt;Control&gt;&lt;Shift&gt;plus</literal>,
* </para></note>
*
* Return value: %TRUE if there was a keyval bound to the keycode/state/group
**/

15
gdk/gdkwindow.c
View File

@ -3152,10 +3152,8 @@ _gdk_window_ref_cairo_surface (GdkWindow *window)
*
* Creates a Cairo context for drawing to @window.
*
* <note><warning>
* Note that calling cairo_reset_clip() on the resulting #cairo_t will
* produce undefined results, so avoid it at all costs.
* </warning></note>
*
* Return value: A newly created Cairo context. Free with
* cairo_destroy() when you are done drawing.
@ -6016,15 +6014,13 @@ gdk_window_set_device_cursor (GdkWindow *window,
* #GdkEventConfigure. gdk_window_get_position() in contrast gets the
* position from the most recent configure event.
*
* <note>
* If @window is not a toplevel, it is much better
* Note: If @window is not a toplevel, it is much better
* to call gdk_window_get_position(), gdk_window_get_width() and
* gdk_window_get_height() instead, because it avoids the roundtrip to
* the X server and because these functions support the full 32-bit
* coordinate space, whereas gdk_window_get_geometry() is restricted to
* the 16-bit coordinates of X11.
*</note>
**/
*/
void
gdk_window_get_geometry (GdkWindow *window,
gint *x,
@ -10616,8 +10612,6 @@ gdk_test_simulate_button (GdkWindow *window,
* property does not exist, then the function returns %FALSE,
* and %GDK_NONE will be stored in @actual_property_type.
*
* <note>
* <para>
* The XGetWindowProperty() function that gdk_property_get()
* uses has a very confusing and complicated set of semantics.
* Unfortunately, gdk_property_get() makes the situation
@ -10625,10 +10619,7 @@ gdk_test_simulate_button (GdkWindow *window,
* undefined), and also prints warnings to stderr in cases where it
* should return a useful error to the program. You are advised to use
* XGetWindowProperty() directly until a replacement function for
* gdk_property_get()
* is provided.
* </para>
* </note>
* gdk_property_get() is provided.
*
* Returns: %TRUE if data was successfully received and stored
* in @data, otherwise %FALSE.

5
gtk/gtkaccessible.c
View File

@ -166,10 +166,11 @@ gtk_accessible_class_init (GtkAccessibleClass *klass)
*
* Sets the #GtkWidget corresponding to the #GtkAccessible.
*
* <note><para>@accessible will not hold a reference to @widget.
* @accessible will not hold a reference to @widget.
* It is the caller's responsibility to ensure that when @widget
* is destroyed, the widget is unset by calling this function
* again with @widget set to %NULL.</para></note>
* again with @widget set to %NULL.
*
* Since: 2.22
*/
void

4
gtk/gtkalignment.c
View File

@ -40,13 +40,9 @@
* Of course, if the scale settings are both set to 1, the alignment settings
* have no effect.
*
* <note>
* <para>
* Note that the desired effect can in most cases be achieved by using the
* #GtkWidget:halign, #GtkWidget:valign and #GtkWidget:margin properties
* on the child widget, so #GtkAlignment should not be used in new code.
* </para>
* </note>
*/
#include "config.h"

2
gtk/gtkbox.c
View File

@ -69,10 +69,8 @@
* fill and padding child properties.
* Use gtk_box_query_child_packing() to query these fields.
*
* <note><para>
* Note that a single-row or single-column #GtkGrid provides exactly
* the same functionality as #GtkBox.
* </para></note>
*/
#include "config.h"

4
gtk/gtkbuildable.c
View File

@ -31,8 +31,8 @@
* main user of this interface is #GtkBuilder. There should be
* very little need for applications to call any of these functions directly.
*
* <note><para>An object only needs to implement this interface if it needs
* to extend the #GtkBuilder format or run any extra routines at deserialization time</para></note>
* An object only needs to implement this interface if it needs to extend the
* #GtkBuilder format or run any extra routines at deserialization time.
*/
#include "config.h"

6
gtk/gtkbuilder.c
View File

@ -1025,11 +1025,9 @@ gtk_builder_add_from_file (GtkBuilder *builder,
* #GError from the #GTK_BUILDER_ERROR, #G_MARKUP_ERROR or #G_FILE_ERROR
* domain.
*
* <note><para>
* If you are adding an object that depends on an object that is not
* its child (for instance a #GtkTreeView that depends on its
* #GtkTreeModel), you have to explicitly list all of them in @object_ids.
* </para></note>
*
* Returns: A positive value on success, 0 if an error occurred
*
@ -1213,11 +1211,9 @@ gtk_builder_add_from_resource (GtkBuilder *builder,
* #GError from the #GTK_BUILDER_ERROR, #G_MARKUP_ERROR or #G_RESOURCE_ERROR
* domain.
*
* <note><para>
* If you are adding an object that depends on an object that is not
* its child (for instance a #GtkTreeView that depends on its
* #GtkTreeModel), you have to explicitly list all of them in @object_ids.
* </para></note>
*
* Returns: A positive value on success, 0 if an error occurred
*
@ -1348,11 +1344,9 @@ gtk_builder_add_from_string (GtkBuilder *builder,
* Upon errors 0 will be returned and @error will be assigned a
* #GError from the #GTK_BUILDER_ERROR or #G_MARKUP_ERROR domain.
*
* <note><para>
* If you are adding an object that depends on an object that is not
* its child (for instance a #GtkTreeView that depends on its
* #GtkTreeModel), you have to explicitly list all of them in @object_ids.
* </para></note>
*
* Returns: A positive value on success, 0 if an error occurred
*

4
gtk/gtkcsscustomproperty.c
View File

@ -190,14 +190,11 @@ gtk_css_custom_property_create_initial_value (GParamSpec *pspec)
* builtin parsing support, so %NULL may be provided for these
* cases.
*
* <note>
* Engines must ensure property registration happens exactly once,
* usually GTK+ deals with theming engines as singletons, so this
* should be guaranteed to happen once, but bear this in mind
* when creating #GtkThemeEngine<!-- -->s yourself.
* </note>
*
* <note>
* In order to make use of the custom registered properties in
* the CSS file, make sure the engine is loaded first by specifying
* the engine property, either in a previous rule or within the same
@ -208,7 +205,6 @@ gtk_css_custom_property_create_initial_value (GParamSpec *pspec)
* -SomeEngine-custom-property: 2;
* }
* ]|
* </note>
*
* Since: 3.0
*

4
gtk/gtkeventbox.c
View File

@ -243,7 +243,6 @@ gtk_event_box_get_visible_window (GtkEventBox *event_box)
* you want to set the background to a different color or
* draw on it.
*
* <note><para>
* There is one unexpected issue for an invisible event box that has its
* window below the child. (See gtk_event_box_set_above_child().)
* Since the input-only window is not an ancestor window of any windows
@ -252,11 +251,10 @@ gtk_event_box_get_visible_window (GtkEventBox *event_box)
* The practical effect of this is if an event isn't in the event
* mask for the descendant window (see gtk_widget_add_events()),
* it won't be received by the event box.
* </para><para>
*
* This problem doesn't occur for visible event boxes, because in
* that case, the event box window is actually the ancestor of the
* descendant windows, not just at the same place on the screen.
* </para></note>
*
* Since: 2.4
*/

4
gtk/gtkflowbox.c
View File

@ -3689,9 +3689,9 @@ gtk_flow_box_class_init (GtkFlowBoxClass *class)
* The minimum number of children to allocate consecutively
* in the given orientation.
*
* <note><para>Setting the minimum children per line ensures
* Setting the minimum children per line ensures
* that a reasonably small height will be requested
* for the overall minimum width of the box.</para></note>
* for the overall minimum width of the box.
*/
g_object_class_install_property (object_class,
PROP_MIN_CHILDREN_PER_LINE,

4
gtk/gtklabel.c
View File

@ -2130,12 +2130,12 @@ gtk_label_set_text (GtkLabel *label,
* Sets a #PangoAttrList; the attributes in the list are applied to the
* label text.
*
* <note><para>The attributes set with this function will be applied
* The attributes set with this function will be applied
* and merged with any other attributes previously effected by way
* of the #GtkLabel:use-underline or #GtkLabel:use-markup properties.
* While it is not recommended to mix markup strings with manually set
* attributes, if you must; know that the attributes will be applied
* to the label after the markup string is parsed.</para></note>
* to the label after the markup string is parsed.
**/
void
gtk_label_set_attributes (GtkLabel *label,

4
gtk/gtkmain.c
View File

@ -1011,21 +1011,17 @@ gtk_init_check (int *argc,
* the option group returned by gtk_get_option_group(),
* you don't have to call gtk_init().
*
* <note><para>
* This function will terminate your program if it was unable to
* initialize the windowing system for some reason. If you want
* your program to fall back to a textual interface you want to
* call gtk_init_check() instead.
* </para></note>
*
* <note><para>
* Since 2.18, GTK+ calls <literal>signal (SIGPIPE, SIG_IGN)</literal>
* during initialization, to ignore SIGPIPE signals, since these are
* almost never wanted in graphical applications. If you do need to
* handle SIGPIPE for some reason, reset the handler after gtk_init(),
* but notice that other libraries (e.g. libdbus or gvfs) might do
* similar things.
* </para></note>
*/
void
gtk_init (int *argc, char ***argv)

2
gtk/gtkmisc.c
View File

@ -45,11 +45,9 @@
* a container in such a way that it expands automatically to fill its
* allocated area, the alignment settings will not alter the widgets position.
*
* <note>
* Note that the desired effect can in most cases be achieved by using the
* #GtkWidget:halign, #GtkWidget:valign and #GtkWidget:margin properties
* on the child widget, so GtkMisc should not be used in new code.
* </note>
*/

2
gtk/gtkplug.c
View File

@ -61,13 +61,11 @@
* integration when embedding a <application>Qt</application> widget
* in GTK+ or vice versa.
*
* <note>
* The #GtkPlug and #GtkSocket widgets are only available when GTK+
* is compiled for the X11 platform and %GDK_WINDOWING_X11 is defined.
* They can only be used on a #GdkX11Display. To use #GtkPlug and
* #GtkSocket, you need to include the <filename>gtk/gtkx.h</filename>
* header.
* </note>
*/
struct _GtkPlugPrivate

8
gtk/gtkpopover.c
View File

@ -1650,11 +1650,9 @@ gtk_popover_get_pointing_to (GtkPopover *popover,
* Sets the preferred position for @popover to appear. If the @popover
* is currently visible, it will be immediately updated.
*
* <note>
* This preference will be respected where possible, although
* on lack of space (eg. if close to the window edges), the
* #GtkPopover may choose to appear on the opposite side
* </note>
* This preference will be respected where possible, although
* on lack of space (eg. if close to the window edges), the
* #GtkPopover may choose to appear on the opposite side
*
* Since: 3.12
**/

6
gtk/gtkrecentmanager.c
View File

@ -32,7 +32,7 @@
* should be displayed only by the applications that have
* registered it.
*
* <note><para>The recently used files list is per user.</para></note>
* The recently used files list is per user.
*
* The #GtkRecentManager acts like a database of all the recently
* used files. You can create new #GtkRecentManager objects, but
@ -78,9 +78,9 @@
* A #GtkRecentManager is the model used to populate the contents of
* one, or more #GtkRecentChooser implementations.
*
* <note><para>The maximum age of the recently used files list is
* Note that the maximum age of the recently used files list is
* controllable through the #GtkSettings:gtk-recent-files-max-age
* property.</para></note>
* property.
*
* Recently used files are supported since GTK+ 2.10.
*/

17
gtk/gtksizerequest.c
View File

@ -433,10 +433,10 @@ gtk_widget_compute_size_for_orientation (GtkWidget *widget,
* Gets whether the widget prefers a height-for-width layout
* or a width-for-height layout.
*
* <note><para>#GtkBin widgets generally propagate the preference of
* #GtkBin widgets generally propagate the preference of
* their child, container widgets need to request something either in
* context of their children or in context of their allocation
* capabilities.</para></note>
* capabilities.
*
* Returns: The #GtkSizeRequestMode preferred by @widget.
*
@ -468,8 +468,7 @@ gtk_widget_get_request_mode (GtkWidget *widget)
*
* Retrieves a widget's initial minimum and natural width.
*
* <note><para>This call is specific to height-for-width
* requests.</para></note>
* This call is specific to height-for-width requests.
*
* The returned request will be modified by the
* GtkWidgetClass::adjust_size_request virtual method and by any
@ -504,7 +503,7 @@ gtk_widget_get_preferred_width (GtkWidget *widget,
*
* Retrieves a widget's initial minimum and natural height.
*
* <note><para>This call is specific to width-for-height requests.</para></note>
* This call is specific to width-for-height requests.
*
* The returned request will be modified by the
* GtkWidgetClass::adjust_size_request virtual method and by any
@ -661,10 +660,10 @@ gtk_widget_get_preferred_height_and_baseline_for_width (GtkWidget *widget,
* to deduce toplevel window and menu sizes as well as child widgets in
* free-form containers such as GtkLayout.
*
* <note><para>Handle with care. Note that the natural height of a height-for-width
* Handle with care. Note that the natural height of a height-for-width
* widget will generally be a smaller size than the minimum height, since the required
* height for the natural width is generally smaller than the required height for
* the minimum width.</para></note>
* the minimum width.
*/
void
_gtk_widget_get_preferred_size_and_baseline (GtkWidget *widget,
@ -730,10 +729,10 @@ _gtk_widget_get_preferred_size_and_baseline (GtkWidget *widget,
* to deduce toplevel window and menu sizes as well as child widgets in
* free-form containers such as GtkLayout.
*
* <note><para>Handle with care. Note that the natural height of a height-for-width
* Handle with care. Note that the natural height of a height-for-width
* widget will generally be a smaller size than the minimum height, since the required
* height for the natural width is generally smaller than the required height for
* the minimum width.</para></note>
* the minimum width.
*
* Use gtk_widget_get_preferred_height_and_baseline_for_width() if you want to support
* baseline alignment.

2
gtk/gtksocket.c
View File

@ -107,13 +107,11 @@
* integration when embedding a <application>Qt</application> widget
* in GTK or vice versa.
*
* <note>
* The #GtkPlug and #GtkSocket widgets are only available when GTK+
* is compiled for the X11 platform and %GDK_WINDOWING_X11 is defined.
* They can only be used on a #GdkX11Display. To use #GtkPlug and
* #GtkSocket, you need to include the <filename>gtk/gtkx.h</filename>
* header.
* </note>
*/
/* Forward declararations */

14
gtk/gtkstylecontext.c
View File

@ -1046,12 +1046,10 @@ gtk_style_context_queue_invalidate_internal (GtkStyleContext *context,
* won't be attached to any widget, so you may want
* to call gtk_style_context_set_path() yourself.
*
* <note>
* This function is only useful when using the theming layer
* separated from GTK+, if you are using #GtkStyleContext to
* theme #GtkWidget<!-- -->s, use gtk_widget_get_style_context()
* in order to get a style context ready to theme the widget.
* </note>
*
* Returns: A newly created #GtkStyleContext.
**/
@ -1091,9 +1089,9 @@ _gtk_style_context_set_widget (GtkStyleContext *context,
* to affect the style of all widgets, use
* gtk_style_context_add_provider_for_screen().
*
* <note><para>If both priorities are the same, A #GtkStyleProvider
* Note: If both priorities are the same, a #GtkStyleProvider
* added through this function takes precedence over another added
* through gtk_style_context_add_provider_for_screen().</para></note>
* through gtk_style_context_add_provider_for_screen().
*
* Since: 3.0
**/
@ -1201,9 +1199,9 @@ gtk_style_context_reset_widgets (GdkScreen *screen)
* GTK+ uses this to make styling information from #GtkSettings
* available.
*
* <note><para>If both priorities are the same, A #GtkStyleProvider
* Note: If both priorities are the same, A #GtkStyleProvider
* added through gtk_style_context_add_provider() takes precedence
* over another added through this function.</para></note>
* over another added through this function.
*
* Since: 3.0
**/
@ -2060,8 +2058,8 @@ _gtk_style_context_check_region_name (const gchar *str)
*
* would apply to even and odd rows, respectively.
*
* <note><para>Region names must only contain lowercase letters
* and '-', starting always with a lowercase letter.</para></note>
* Region names must only contain lowercase letters
* and '-', starting always with a lowercase letter.
*
* Since: 3.0
**/

50
gtk/gtkwidget.c
View File

@ -5219,10 +5219,10 @@ gtk_widget_queue_draw (GtkWidget *widget)
* For example, when you change the text in a #GtkLabel, #GtkLabel
* queues a resize to ensure there's enough space for the new text.
*
* <note><para>You cannot call gtk_widget_queue_resize() on a widget
* Note that you cannot call gtk_widget_queue_resize() on a widget
* from inside its implementation of the GtkWidgetClass::size_allocate
* virtual method. Calls to gtk_widget_queue_resize() from inside
* GtkWidgetClass::size_allocate will be silently ignored.</para></note>
* GtkWidgetClass::size_allocate will be silently ignored.
**/
void
gtk_widget_queue_resize (GtkWidget *widget)
@ -6701,9 +6701,9 @@ _gtk_widget_draw (GtkWidget *widget,
* is fine to modify the context with cairo_save() and
* cairo_push_group() prior to calling this function.
*
* <note><para>Special purpose widgets may contain special code for
* Note that special-purpose widgets may contain special code for
* rendering to the screen and might appear differently on screen
* and when rendered using gtk_widget_draw().</para></note>
* and when rendered using gtk_widget_draw().
*
* Since: 3.0
**/
@ -9037,26 +9037,23 @@ _gtk_widget_get_modifier_properties (GtkWidget *widget)
* you may not think of as containers, for instance #GtkButton<!-- -->s,
* are actually containers.
*
* <note><para>
* This API is mostly meant as a quick way for applications to
* change a widget appearance. If you are developing a widgets
* library and intend this change to be themeable, it is better
* done by setting meaningful CSS classes and regions in your
* widget/container implementation through gtk_style_context_add_class()
* and gtk_style_context_add_region().
* </para><para>
*
* This way, your widget library can install a #GtkCssProvider
* with the %GTK_STYLE_PROVIDER_PRIORITY_FALLBACK priority in order
* to provide a default styling for those widgets that need so, and
* this theming may fully overridden by the user's theme.
* </para></note>
* <note><para>
*
* Note that for complex widgets this may bring in undesired
* results (such as uniform background color everywhere), in
* these cases it is better to fully style such widgets through a
* #GtkCssProvider with the %GTK_STYLE_PROVIDER_PRIORITY_APPLICATION
* priority.
* </para></note>
*
* Since: 3.0
*/
@ -9826,19 +9823,16 @@ gtk_widget_render_icon_pixbuf (GtkWidget *widget,
*
* Sets a non default parent window for @widget.
*
* For GtkWindow classes, setting a @parent_window effects whether
* For #GtkWindow classes, setting a @parent_window effects whether
* the window is a toplevel window or can be embedded into other
* widgets.
*
* <note><para>
* For GtkWindow classes, this needs to be called before the
* For #GtkWindow classes, this needs to be called before the
* window is realized.
* </para></note>
*
**/
*/
void
gtk_widget_set_parent_window (GtkWidget *widget,
GdkWindow *parent_window)
gtk_widget_set_parent_window (GtkWidget *widget,
GdkWindow *parent_window)
{
GdkWindow *old_parent_window;
@ -14997,7 +14991,7 @@ gtk_widget_get_requisition (GtkWidget *widget,
* by calling gtk_widget_set_has_window(). This is usually done in the
* widget's init() function.
*
* <note><para>This function does not add any reference to @window.</para></note>
* Note that this function does not add any reference to @window.
*
* Since: 2.18
*/
@ -15988,8 +15982,8 @@ gtk_widget_init_template (GtkWidget *widget)
*
* For convenience, gtk_widget_class_set_template_from_resource() is also provided.
*
* <note><para>Any class that installs templates must call gtk_widget_init_template()
* in the widget's instance initializer</para></note>
* Note that any class that installs templates must call gtk_widget_init_template()
* in the widget's instance initializer.
*
* Since: 3.10
*/
@ -16012,8 +16006,8 @@ gtk_widget_class_set_template (GtkWidgetClass *widget_class,
*
* A convenience function to call gtk_widget_class_set_template().
*
* <note><para>Any class that installs templates must call gtk_widget_init_template()
* in the widget's instance initializer</para></note>
* Note that any class that installs templates must call gtk_widget_init_template()
* in the widget's instance initializer.
*
* Since: 3.10
*/
@ -16057,8 +16051,8 @@ gtk_widget_class_set_template_from_resource (GtkWidgetClass *widget_class,
* Declares a @callback_symbol to handle @callback_name from the template XML
* defined for @widget_type. See gtk_builder_add_callback_symbol().
*
* <note><para>This must be called from a composite widget classes class
* initializer after calling gtk_widget_class_set_template()</para></note>
* Note that this must be called from a composite widget classes class
* initializer after calling gtk_widget_class_set_template().
*
* Since: 3.10
*/
@ -16089,8 +16083,8 @@ gtk_widget_class_bind_template_callback_full (GtkWidgetClass *widget_class,
* For use in lanuage bindings, this will override the default #GtkBuilderConnectFunc to be
* used when parsing GtkBuilder xml from this class's template data.
*
* <note><para>This must be called from a composite widget classes class
* initializer after calling gtk_widget_class_set_template()</para></note>
* Note that this must be called from a composite widget classes class
* initializer after calling gtk_widget_class_set_template().
*
* Since: 3.10
*/
@ -16142,8 +16136,8 @@ gtk_widget_class_set_connect_func (GtkWidgetClass *widget_class,
* gtk_widget_class_bind_template_child_private() and gtk_widget_class_bind_template_child_internal_private()
* might be more convenient to use.
*
* <note><para>This must be called from a composite widget classes class
* initializer after calling gtk_widget_class_set_template()</para></note>
* Note that this must be called from a composite widget classes class
* initializer after calling gtk_widget_class_set_template().
*
* Since: 3.10
*/

4
gtk/gtkwidgetpath.c
View File

@ -978,8 +978,8 @@ gtk_widget_path_iter_has_class (const GtkWidgetPath *path,
* the hierarchy defined in @path. See
* gtk_style_context_add_region().
*
* <note><para>Region names must only contain lowercase letters
* and '-', starting always with a lowercase letter.</para></note>
* Region names must only contain lowercase letters
* and '-', starting always with a lowercase letter.
*
* Since: 3.0
**/