Documentation updates

* doc/hildon-sections.txt
* hildon/hildon-button.c
* hildon/hildon-edit-toolbar.c
* hildon/hildon-gtk.[ch]
* hildon/hildon-main.c
* hildon/hildon-program.c
* hildon/hildon-stackable-window.c:
Documentation updates

9 files changed, 75 insertions, 37 deletions

diff --git a/ChangeLog b/ChangeLog
index 1121c04..b3b347e 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,14 @@
+2009-09-03  Alberto Garcia  <agarcia@igalia.com>
+
+	* doc/hildon-sections.txt
+	* hildon/hildon-button.c
+	* hildon/hildon-edit-toolbar.c
+	* hildon/hildon-gtk.[ch]
+	* hildon/hildon-main.c
+	* hildon/hildon-program.c
+	* hildon/hildon-stackable-window.c:
+	Documentation updates
+
 2009-08-28  Alberto Garcia  <agarcia@igalia.com>
 
 	* hildon/hildon-app-menu.c
diff --git a/doc/hildon-sections.txt b/doc/hildon-sections.txt
index abded58..91d97a3 100644
--- a/doc/hildon-sections.txt
+++ b/doc/hildon-sections.txt
@@ -1232,6 +1232,7 @@ HILDON_CHECK_VERSION
 <SECTION>
 <FILE>hildon-gtk</FILE>
 <TITLE>Additions to GTK+</TITLE>
+HildonPortraitFlags
 hildon_gtk_menu_new
 hildon_gtk_button_new
 hildon_gtk_toggle_button_new
@@ -1246,7 +1247,6 @@ hildon_gtk_icon_view_set_ui_mode
 hildon_gtk_window_set_do_not_disturb
 hildon_gtk_window_set_progress_indicator
 hildon_gtk_window_take_screenshot
-HildonPortraitFlags
 hildon_gtk_window_set_portrait_flags
 hildon_gtk_hscale_new
 hildon_gtk_vscale_new
diff --git a/hildon/hildon-button.c b/hildon/hildon-button.c
index bd2b8e3..58639e5 100644
--- a/hildon/hildon-button.c
+++ b/hildon/hildon-button.c
@@ -1,7 +1,7 @@
 /*
  * This file is a part of hildon
  *
- * Copyright (C) 2008 Nokia Corporation, all rights reserved.
+ * Copyright (C) 2008, 2009 Nokia Corporation, all rights reserved.
  *
  * Contact: Rodrigo Novo <rodrigo.novo@nokia.com>
  *
@@ -20,16 +20,16 @@
  * SECTION:hildon-button
  * @short_description: Two-label buttons in the Hildon framework.
  *
- * The #HildonButton is a clickable button for Hildon applications.
- * It is derived from the #GtkButton widget and provides
- * additional commodities specific to the Hildon framework.
+ * #HildonButton is a clickable button for Hildon applications. It is
+ * derived from the #GtkButton widget and provides additional
+ * commodities specific to the Hildon framework.
  *
  * The height of a #HildonButton can be set to either "finger" height
  * or "thumb" height. It can also be configured to use halfscreen or
  * fullscreen width. Alternatively, either dimension can be set to
  * "auto" so it behaves like a standard #GtkButton.
  *
- * The #HildonButton can hold any valid child widget, but it usually
+ * A #HildonButton can hold any valid child widget, but it usually
  * contains two labels, named title and value, and it can also contain
  * an image. The contents of the button are packed together inside a
  * #GtkAlignment and they do not expand by default (they don't use the
@@ -829,7 +829,7 @@ hildon_button_set_image_position                (HildonButton    *button,
  * to change @xscale or @yscale you can just use
  * gtk_button_set_alignment() instead.
  *
- * Note that for this method to work properly the, child widget of
+ * Note that for this method to work properly, the child widget of
  * @button must be a #GtkAlignment. That's what #HildonButton uses by
  * default, so this function will work unless you add a custom widget
  * to @button.
diff --git a/hildon/hildon-edit-toolbar.c b/hildon/hildon-edit-toolbar.c
index 9b8d910..7db0ecc 100644
--- a/hildon/hildon-edit-toolbar.c
+++ b/hildon/hildon-edit-toolbar.c
@@ -1,7 +1,7 @@
 /*
  * This file is a part of hildon
  *
- * Copyright (C) 2008 Nokia Corporation, all rights reserved.
+ * Copyright (C) 2008, 2009 Nokia Corporation, all rights reserved.
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU Lesser Public License as published by
@@ -33,6 +33,10 @@
  * To add a #HildonEditToolbar to a window use
  * hildon_window_set_edit_toolbar().
  *
+ * This toolbar is meant to replace the window title bar by emulating
+ * its appearance, so you should put the window in full screen mode
+ * with gtk_window_fullscreen().
+ *
  * <example>
  * <title>HildonEditToolbar example</title>
  * <programlisting>
diff --git a/hildon/hildon-gtk.c b/hildon/hildon-gtk.c
index e1b6f3d..2583682 100644
--- a/hildon/hildon-gtk.c
+++ b/hildon/hildon-gtk.c
@@ -1,7 +1,7 @@
 /*
  * This file is a part of hildon
  *
- * Copyright (C) 2008 Nokia Corporation, all rights reserved.
+ * Copyright (C) 2008, 2009 Nokia Corporation, all rights reserved.
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU Lesser Public License as published by
@@ -114,8 +114,8 @@ hildon_gtk_menu_new                             (void)
  * This is a convenience function to create a #GtkButton setting its
  * size to one of the pre-defined Hildon sizes.
  *
- * Buttons created with this function also override the
- * "gtk-button-images" setting. Images set using
+ * Buttons created with this function also override
+ * #GtkSettings:gtk-button-images. Images set using
  * gtk_button_set_image() are always shown.
  *
  * Buttons created using this function have #GtkButton:focus-on-click
@@ -140,8 +140,8 @@ hildon_gtk_button_new                           (HildonSizeType size)
  * This is a convenience function to create a #GtkToggleButton setting
  * its size to one of the pre-defined Hildon sizes.
  *
- * Buttons created with this function also override the
- * "gtk-button-images" setting. Images set using
+ * Buttons created with this function also override
+ * #GtkSettings:gtk-button-images. Images set using
  * gtk_button_set_image() are always shown.
  *
  * Buttons created using this function have #GtkButton:focus-on-click
@@ -168,8 +168,8 @@ hildon_gtk_toggle_button_new                    (HildonSizeType size)
  * This is a convenience function to create a #GtkRadioButton setting
  * its size to one of the pre-defined Hildon sizes.
  *
- * Buttons created with this function also override the
- * "gtk-button-images" setting. Images set using
+ * Buttons created with this function also override
+ * #GtkSettings:gtk-button-images. Images set using
  * gtk_button_set_image() are always shown.
  *
  * Buttons created using this function have #GtkButton:focus-on-click
@@ -196,8 +196,8 @@ hildon_gtk_radio_button_new                     (HildonSizeType  size,
  * This is a convenience function to create a #GtkRadioButton setting
  * its size to one of the pre-defined Hildon sizes.
  *
- * Buttons created with this function also override the
- * "gtk-button-images" setting. Images set using
+ * Buttons created with this function also override
+ * #GtkSettings:gtk-button-images. Images set using
  * gtk_button_set_image() are always shown.
  *
  * Buttons created using this function have #GtkButton:focus-on-click
diff --git a/hildon/hildon-gtk.h b/hildon/hildon-gtk.h
index 4816bfc..49b3d46 100644
--- a/hildon/hildon-gtk.h
+++ b/hildon/hildon-gtk.h
@@ -1,7 +1,7 @@
 /*
  * This file is a part of hildon
  *
- * Copyright (C) 2008 Nokia Corporation, all rights reserved.
+ * Copyright (C) 2008, 2009 Nokia Corporation, all rights reserved.
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU Lesser Public License as published by
@@ -70,6 +70,26 @@ void
 hildon_gtk_window_set_do_not_disturb            (GtkWindow *window,
                                                  gboolean   dndflag);
 
+/**
+ * HildonPortraitFlags:
+ *
+ * These flags are used to tell the window manager whether the current
+ * window needs to be in portrait or landscape mode.
+ *
+ * If no flags are set then the window is meant to be used in
+ * landscape mode only.
+ *
+ * If %HILDON_PORTRAIT_MODE_REQUEST is set then the window is meant to
+ * be used in portrait mode only.
+ *
+ * If only %HILDON_PORTRAIT_MODE_SUPPORT is set then the current
+ * orientation will be kept, no matter if it's portrait or landscape.
+ *
+ * It is important to note that, while these flags can be used to
+ * change between portrait and landscape according to the physical
+ * orientation of the display, Hildon does not provide any method to
+ * obtain this information.
+ **/
 typedef enum {
     HILDON_PORTRAIT_MODE_REQUEST = 1 << 0,
     HILDON_PORTRAIT_MODE_SUPPORT = 1 << 1
diff --git a/hildon/hildon-main.c b/hildon/hildon-main.c
index 194af14..65cd4dd 100644
--- a/hildon/hildon-main.c
+++ b/hildon/hildon-main.c
@@ -1,7 +1,7 @@
 /*
  * This file is part of the hildon library
  *
- * Copyright (C) 2008 Nokia Corporation, all rights reserved.
+ * Copyright (C) 2008, 2009 Nokia Corporation, all rights reserved.
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public License
@@ -28,10 +28,10 @@
  * to the window system display, and parses some standard command line
  * arguments. See also gtk_init() to know more details on this topic.
  *
- * Hildon should be initialized by using hildon_gtk_init(). Notice this function
- * also initialize gtk by calling gtk_init(). In case you need a customized
- * initialization of GTK+ library you could use hildon_init() after the
- * customized GTK+ initialization.
+ * Hildon should be initialized by using hildon_gtk_init(). Note that
+ * this function also initializes gtk by calling gtk_init(). In case
+ * you need a customized initialization of the GTK+ library you have
+ * to use hildon_init() after the customized GTK+ initialization.
  *
  * <example>
  * <title>Typical <function>main</function> function for a Hildon application</title>
diff --git a/hildon/hildon-program.c b/hildon/hildon-program.c
index ccac791..86e866c 100644
--- a/hildon/hildon-program.c
+++ b/hildon/hildon-program.c
@@ -593,8 +593,6 @@ hildon_program_get_can_hibernate                (HildonProgram *self)
  *
  * This method does not support #HildonAppMenu<!-- -->s. See
  * hildon_program_set_common_app_menu() for that.
- *
- * Since: 2.2
  **/
 void
 hildon_program_set_common_menu                  (HildonProgram *self, 
diff --git a/hildon/hildon-stackable-window.c b/hildon/hildon-stackable-window.c
index 1b2d6bb..c10d433 100644
--- a/hildon/hildon-stackable-window.c
+++ b/hildon/hildon-stackable-window.c
@@ -1,7 +1,7 @@
 /*
  * This file is a part of hildon
  *
- * Copyright (C) 2008 Nokia Corporation, all rights reserved.
+ * Copyright (C) 2008, 2009 Nokia Corporation, all rights reserved.
  *
  * Contact: Rodrigo Novo <rodrigo.novo@nokia.com>
  *
@@ -27,27 +27,32 @@
  * @short_description: Stackable top-level window in the Hildon framework.
  * @see_also: #HildonWindowStack, #HildonProgram, #HildonWindow
  *
- * The #HildonStackableWindow is a
- * top-level window that can be stacked in a #HildonWindowStack. It is derived
- * from #HildonWindow. Applications that use stackable windows are organized
- * in a hierarchical way so users can go from any window back to the
- * application's root window.
+ * #HildonStackableWindow is a top-level window that can be stacked on
+ * top of others. It is derived from #HildonWindow. Applications that
+ * use stackable windows are organized in a hierarchical way so users
+ * can go from any window back to the previous one or directly to the
+ * stack's root window.
  *
  * The user can only see and interact with the window on top of the
  * stack. Although all other windows are mapped and visible, they are
- * obscured by the topmost one so in practice they appear as if they
- * were hidden.
+ * obscured by the topmost one so in practice the user will see the
+ * whole stack as if it was a single window.
  *
  * To add a window to the stack, just use gtk_widget_show(). The
  * previous one will be obscured by the new one. When the new window
  * is destroyed, the previous one will appear again.
  *
  * Alternatively, you can remove a window from the top of the stack
- * without destroying it by using hildon_window_stack_pop(). The
- * window will be automatically hidden and the previous one will
- * appear.
+ * without destroying it by using gtk_widget_hide(). The window will
+ * be hidden and the previous one will appear automatically.
  *
- * For advanced details on stack handling, see #HildonWindowStack
+ * It is important to note that all #HildonStackableWindow<!-- -->s on
+ * a stack are always mapped and visible (from the Gtk point of view)
+ * and all visible #HildonStackableWindow<!-- -->s are always on a
+ * stack.
+ *
+ * To see how to manage multiple stacks per application and for other
+ * advanced details on stack handling, see #HildonWindowStack
  *
  * <example>
  * <title>Basic HildonStackableWindow example</title>