Better mark GtkAlignment as deprecated

- Move the class to the Deprecated section.
- Warning at the bottom of the class description.
- A missing property was not marked as deprecated.
- Update doc of gtk_container_set_border_width() to not mention
  GtkAlignment.

https://bugzilla.gnome.org/show_bug.cgi?id=736622

docs/reference/gtk/gtk-docs.sgml

@@ -79,7 +79,6 @@
       <xi:include href="xml/gtkactionbar.xml" />
       <xi:include href="xml/gtkheaderbar.xml" />
       <xi:include href="xml/gtkoverlay.xml" />
-      <xi:include href="xml/gtkalignment.xml" />
       <xi:include href="xml/gtkbbox.xml" />
       <xi:include href="xml/gtkpaned.xml" />
       <xi:include href="xml/gtklayout.xml" />
@@ -340,6 +339,7 @@
       <xi:include href="xml/gtkarrow.xml" />
       <xi:include href="xml/gtkstatusicon.xml" />
       <xi:include href="xml/gtkthemingengine.xml" />
+      <xi:include href="xml/gtkalignment.xml" />
     </chapter>
 
   </part>

gtk/deprecated/gtkalignment.c

@@ -40,9 +40,10 @@
  * Of course, if the scale settings are both set to 1, the alignment settings
  * have no effect.
  *
- * Note that the desired effect can in most cases be achieved by using the
+ * GtkAlignment has been deprecated in 3.14 and should not be used in
- * #GtkWidget:halign, #GtkWidget:valign and #GtkWidget:margin properties
+ * newly-written code. The desired effect can be achieved by using the
- * on the child widget, so #GtkAlignment should not be used in new code.
+ * #GtkWidget:halign, #GtkWidget:valign and #GtkWidget:margin properties on the
+ * child widget.
  */
 
 #include "config.h"
@@ -143,7 +144,7 @@ gtk_alignment_class_init (GtkAlignmentClass *class)
                                                       0.0,
                                                       1.0,
                                                       0.5,
-                                                      GTK_PARAM_READWRITE));
+                                                      GTK_PARAM_READWRITE|G_PARAM_DEPRECATED));
    
   g_object_class_install_property (gobject_class,
                                    PROP_YALIGN,

gtk/gtkcontainer.c

@@ -1498,10 +1498,9 @@ _gtk_container_set_border_width_set (GtkContainer *container,
  * around the outside of the container. The only exception to this is
  * #GtkWindow; because toplevel windows can’t leave space outside,
  * they leave the space inside. The border is added on all sides of
- * the container. To add space to only one side, one approach is to
+ * the container. To add space to only one side, use a specific
- * create a #GtkAlignment widget, call gtk_widget_set_size_request()
+ * #GtkWidget:margin property on the child widget, for example
- * to give it a size, and place it on the side of the container as
+ * #GtkWidget:margin-top.
- * a spacer.
  **/
 void
 gtk_container_set_border_width (GtkContainer *container,