diff --git a/gst/gstelement.c b/gst/gstelement.c
index aeeb6eb3d7..c611b53f24 100644
--- a/gst/gstelement.c
+++ b/gst/gstelement.c
@@ -1701,7 +1701,7 @@ gst_element_get_state (GstElement * element,
  * @element: a #GstElement to abort the state of.
  *
  * Abort the state change of the element. This function is used
- * by elements that do asynchronous state changes and find out 
+ * by elements that do asynchronous state changes and find out
  * something is wrong.
  *
  * This function should be called with the STATE_LOCK held.
@@ -1845,7 +1845,6 @@ gst_element_set_state (GstElement * element, GstState state)
   GST_TIME_TO_TIMEVAL (0, tv);
   ret = gst_element_get_state (element, &current, &pending, &tv);
 
-  /* get the element state lock */
   GST_STATE_LOCK (element);
   /* this is the state we should go to */
   GST_STATE_FINAL (element) = state;
@@ -1868,7 +1867,7 @@ gst_element_set_state (GstElement * element, GstState state)
 
   oclass = GST_ELEMENT_GET_CLASS (element);
 
-  /* We always perform at least one state change, even if the 
+  /* We always perform at least one state change, even if the
    * current state is equal to the required state. This is needed
    * for bins that sync their children. */
   do {
diff --git a/gst/gstelement.h b/gst/gstelement.h
index b038ae677e..97492a8c2c 100644
--- a/gst/gstelement.h
+++ b/gst/gstelement.h
@@ -263,6 +263,15 @@ G_STMT_START {								\
 
 /* the state change mutexes and conds */
 #define GST_STATE_GET_LOCK(elem)               (GST_ELEMENT_CAST(elem)->state_lock)
+
+/**
+ * GST_STATE_LOCK:
+ * @elem:   the #GstElement to take the state lock on
+ *
+ * Takes the state lock on the element.
+ * This function is used by the core.  It is taken while getting or setting
+ * the state, during state changes, and while finalizing.
+ */
 #define GST_STATE_LOCK(elem)                   g_mutex_lock(GST_STATE_GET_LOCK(elem))
 #define GST_STATE_TRYLOCK(elem)                g_mutex_trylock(GST_STATE_GET_LOCK(elem))
 #define GST_STATE_UNLOCK(elem)                 g_mutex_unlock(GST_STATE_GET_LOCK(elem))
@@ -284,9 +293,12 @@ struct _GstElement
   guint8                current_state;
   guint8                pending_state;
   guint8                final_state;
-  gboolean              state_error; /* flag is set when the element has an error in the last state
-                                        change. it is cleared when doing another state change. */
-  gboolean		no_preroll;  /* flag is set when the element cannot preroll */
+  gboolean              state_error; /* Flag is set when the element has an
+                                      * error in the last state change.
+                                      * It is cleared when doing another
+                                      * state change. */
+  gboolean		no_preroll;  /* Flag is set when the element cannot
+                                      * preroll */
   /*< public >*/ /* with LOCK */
   GstBus	       *bus;
 
diff --git a/gst/gstpad.c b/gst/gstpad.c
index f50cb8b9e1..6590a027ad 100644
--- a/gst/gstpad.c
+++ b/gst/gstpad.c
@@ -501,7 +501,8 @@ post_activate_switch (GstPad * pad, gboolean new_active)
  * @pad: the #GstPad to activate or deactivate.
  * @active: whether or not the pad should be active.
  *
- * Activates or deactivates the given pad. Must be called with the %GST_STATE_LOCK.
+ * Activates or deactivates the given pad.
+ * Must be called with the parent element's #GST_STATE_LOCK held.
  * Normally called from within core state change functions.
  *
  * If @active, makes sure the pad is active. If it is already active, either in
@@ -512,9 +513,9 @@ post_activate_switch (GstPad * pad, gboolean new_active)
  * gst_pad_activate_push() or gst_pad_activate_pull(), as appropriate, with a
  * FALSE argument.
  *
- * Returns: TRUE if the operation was successfull.
+ * Returns: #TRUE if the operation was successful.
  *
- * MT safe. Must be called with %GST_STATE_LOCK.
+ * MT safe. Must be called with parent element's #GST_STATE_LOCK held.
  */
 gboolean
 gst_pad_set_active (GstPad * pad, gboolean active)