[glib] glist: Clarify that g_list_nth() is expensive

[Philip Withnall <pwithnall src gnome org>]

commit 984576c01e54f335a1a2cde9e6f235946bd35f96
Author: Philip Withnall <philip withnall collabora co uk>
Date:   Fri Dec 19 18:53:54 2014 +0000

    glist: Clarify that g_list_nth() is expensive
    
    Just in case people have forgotten their basic algorithms course. Seen
    in some pretty terrible code in the wild; hopefully mentioning the cost
    in the documentation will make people think twice about using a counter
    variable when iterating over a linked list.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=741779

 glib/glist.c |    8 ++++++++
 1 files changed, 8 insertions(+), 0 deletions(-)
---
diff --git a/glib/glist.c b/glib/glist.c
index 1639a9f..527f89c 100644
--- a/glib/glist.c
+++ b/glib/glist.c
@@ -733,6 +733,10 @@ g_list_reverse (GList *list)
  *
  * Gets the element at the given position in a #GList.
  *
+ * This iterates over the list until it reaches the @n-th position. If you
+ * intend to iterate over every element, it is better to use a for-loop as
+ * described in the #GList introduction.
+ *
  * Returns: the element, or %NULL if the position is off 
  *     the end of the #GList
  */
@@ -773,6 +777,10 @@ g_list_nth_prev (GList *list,
  *
  * Gets the data of the element at the given position.
  *
+ * This iterates over the list until it reaches the @n-th position. If you
+ * intend to iterate over every element, it is better to use a for-loop as
+ * described in the #GList introduction.
+ *
  * Returns: the element's data, or %NULL if the position 
  *     is off the end of the #GList
  */