FreeLists / haiku-doc / [haiku-doc] Final diff for List.dox

[David Weizades <ddewbofh@xxxxxxxxxxx>]

Hi, 

Here's the finished proposal for the List.dox diff. Been over it with a few 
times and everything appears to be in order. It should apply from the main 
haiku dir without any problems. Everything's 80-char checked, there are no odd 
line-breaks and hopefully nothing left for the spellcheckers to correct. ;) 

Keep in mind that this is the first time I've worked on a project where I had 
to supply patches to a mailing-list so I'm unaccustomed to the procedures. 

Enjoy 
Dave

_________________________________________________________________
Prova Live.com: här kan du skapa din egen onlinevärld - med nyheter, sport, 
väder och mycket annat.
http://www.live.com/getstarted

Index: docs/user/support/List.dox
===================================================================
--- docs/user/support/List.dox  (revision 21193)
+++ docs/user/support/List.dox  (arbetskopia)
@@ -2,8 +2,12 @@
  * Copyright 2007, Haiku, Inc. All Rights Reserved.
  * Distributed under the terms of the MIT License.
  *
- * Documentation by:
- *  Niels Sascha Reedijk <niels.reedijk@xxxxxxxxx>
+ * Authors:
+ * Niels Sascha Reedijk <niels.reedijk@xxxxxxxxx>
+ * 
+ * Proofreading:
+ * David Weizades <ddewbofh@xxxxxxxxxxx>
+ *
  * Corresponds to:
  *   /trunk/headers/os/support/List.h  rev 19972
  *   /trunk/src/kits/support/List.cpp  rev 18649
@@ -22,27 +26,27 @@
     objects.
 
   This class is designed to be used for a variety of tasks. Unlike similar
-  implementations in other libraries, this class is not based on templates,
-  and as such is inherently not typed. So it will be the job of the coder to
-  make sure proper data will be entered, since the compiler cannot check this.
+  implementations in other libraries, this class is not based on templates
+  and as such is inherently not typed. So it will be the job of the programmer
+  to make sure proper data is entered since the compiler cannot check this
+  itself.
 
-  BList contains a list of items that will grow and shrink depending on
-  how much items are in it. So you will not have to do any of the
-  memory management. Furthermore, it's ordered. Those properties make it
-  useful in a whole range of situations, for example in the interface kit in 
-  the BListView class.
+  BList contains a list of items that will grow and shrink depending on how
+  many items are in it. So you will not have to do any of the memory management
+  nor any ordering. These properties makes it useful in a whole range of
+  situations such as the interface kit within the BListView class.
 
-  A note on ownership of the objects might come in handy. BList at no time
-  assumes ownership of the objects, so removing items from the list will
-  only remove those items from the list, it will not delete the item. In the
-  same spirit you should also make sure that before you might delete an
-  object that's in a list, you will remove it from the list first. 
+  A note on the ownership of the objects might come in handy. BList never
+  assumes ownership of the objects, removing items from the list will
+  only remove the entries from the list not delete the items themselves. In the
+  same way you should also make sure that before you might delete an object
+  that's in a list, you will have to remove it from the list first.
 
   \warning This class is not thread-safe.
 
-  The class implements methods to add and remove items, reorder items,
-  retrieve items, querying for items and some advanced methods which let
-  you perform a certain tasks to all the items of the list.
+  The class implements methods to add, remove, reorder, retrieve, query
+  items as well as some advanced methods which let you perform a task on all 
the
+  items in the list.
 */
 
 /*!
@@ -50,21 +54,21 @@
   \brief Create a new list with a number of empty slots.
 
   The memory management of this class allocates new memory per block. The
-  \c count parameter can be tweaked to determine the size of those blocks.
-  In general, if you know your list is only going to contain a fixed maximum
-  number of items, pass that value. If you expect your list to have very few 
-  items, it's probably safe to choose a low number. This is as to prevent the 
-  list from taking up unneccesary memory. If you expect the list to contain a 
-  large number of items, choose a higher value, since every time the memory is 
-  full, all the items have to be copied into a new piece of allocated memory 
-  which is an expensive operation.
+  \c count parameter can be tweaked to determine the size of these blocks.
+  In general, if you know your list is only going to contain a certain number 
of
+  items at most, you can pass that value. If you expect your list to have very
+  few items, it's safe to choose a low number. This is to prevent the list from
+  taking up unneeded memory. If you expect the list to contain  a large number
+  of items, choose a higher value. Every time the memory is full, all the items
+  have to be copied into a new piece of allocated memory which, in turn, is an
+  expensive operation.
 
-  If you are unsure, you don't have to break your head over this. As long as 
-  you don't use a lot of lists or as long as the list isn't used in one of the
+  If you are unsure, you don't have to overthink this. Just make sure you don't
+  use a lot of lists and as long as the list isn't used in one of the
   performance critical parts of the code, you are safe to go with the default
-  value.
+  values.
 
-  \param count The size of the blocks of memory allocated.
+  \param count The size of the blocks allocated in memory.
 */
 
 /*!
@@ -98,7 +102,7 @@
   \param item The item to add.
   \param index The place in the list.
   \retval true The item was added.
-  \retval false Item was not added. Either the index was  negative or invalid,
+  \retval false Item was not added. Either the index is negative or invalid,
     or resizing the list failed.
   \see AddItem(void *item)
 */
@@ -133,12 +137,12 @@
   \fn bool BList::AddList(const BList *list)
   \brief Append a list to this list.
 
-  Note that the \a list parameter is \c const, so the original list will not
+  Note that the \a list parameter is a \c const, so the original list will not
   be altered.
 
   \param list The list to be appended.
   \retval true The list was appended. 
-  \retval false Failed to append the list, due to the fact that resizing our
+  \retval false Failed to append the list, due to the resizing of our
     list failed. 
   \see AddList(const BList *list, int32 index)
 */
@@ -208,7 +212,7 @@
   The function should take two \c const pointers as arguments and should return
   an integer.
 
-  For an example, see the Compare(const BString *, const BString *) function. 
+  For an example, see the Compare(const BString *, const BString *) function.
 */
 
 /*!
@@ -225,13 +229,13 @@
   \fn bool BList::MoveItem(int32 fromIndex, int32 toIndex)
   \brief Move an item to a new place
 
-  This moves a list item from posititon a to position b, moving the 
appropriate 
-  block of list elements to make up for the move.  For example, in the array:
+  This moves a list item from position A to position B, moving the appropriate
+  block of list elements to make up for the move.  For example, in  the array:
   \verbatim
 A B C D E F G H I J
   \endverbatim
 
-  Moveing 1(B)->6(G) would result in this:
+  Moving 1(B)->6(G) would result in this:
   \verbatim
 A C D E F G B H I J
   \endverbatim
@@ -239,7 +243,7 @@
   \param fromIndex The original location.
   \param toIndex The new location.
   \retval true Move succeeded.
-  \retval false Move failed since the indexes were invalid.
+  \retval false Move failed due to the indexes being invalid.
 */
 
 //! @}
@@ -264,7 +268,7 @@
   \fn void *BList::FirstItem() const
   \brief Get the first item.
   
-  \return A pointer to the first item, or \c NULL if the list is empty.
+  \return A pointer to the first item or \c NULL if the list is empty.
 */
 
 /*!
@@ -281,7 +285,7 @@
 /*!
   \fn void *BList::LastItem() const
   \brief Get the last item.
-  \return A pointer to the last item, or \c NULL if the list is empty.
+  \return A pointer to the last item or \c NULL if the list is empty.
 */
 
 /*!
@@ -289,16 +293,16 @@
   \brief Return the internal list of objects.
 
   This method will return a pointer to the internal pointer list. This means
-  you should be careful   what you are doing, since you are directly working
-  with the internals of the class.
+  that you should be careful what you are doing, since you are working with the
+  internals of the class directly.
 
-  It is definately not a good idea to make any changes to the list, since it
-  will mess up the internal consistency. 
+  It is not a good idea to make any changes to the list, since that will mess
+  up the internal consistency.
 
-  \warning If there is anything you want for which you need the list of
-    objects, please realize that that probably means that what you want to do
-    is a bad idea to begin with. Avoid this method. The list of objects doesn't
-    belong to you. Check if DoForEach() can help you.
+  \warning If there is anything you want, for which you need the list of
+    objects, please understand that that probably means that what you want to 
do
+    is a bad idea to begin with and you should avoid this method. The list of
+    objects doesn't belong to you. See if DoForEach() can help you out instead.
   \return The internal list of pointers.
 */
 
@@ -344,9 +348,9 @@
   \fn void BList::DoForEach(bool (*func)(void* item))
   \brief Perform an action on every item in the list.
 
-  If one of the actions on the items fails, meaning that the \a func function
-  returned \c false, then the processing of the list will be stopped.
-
+  If one of the actions on the items fails it means that the \a func function
+  returned \c false and the processing of the list will be stopped.
+  
   \param func A function that takes a \c void * argument and returns a boolean.
 */
 
@@ -354,10 +358,10 @@
   \fn void BList::DoForEach(bool (*func)(void* item, void* arg2), void *arg2)
   \brief Perform an action on every item in the list with an argument.
 
-  If one of the actions on the items fails, meaning that the \a func function
-  returned \c false, then the processing of the list will be stopped.
+  If one of the actions on the items fails it means that the \a func function
+  returned \c false and the processing of the list will be stopped.
 
-  \param func A function with the first \c void * argument being the item,
+  \param func A function with the first \c void * argument being the item
     and the second \c void * being the argument that you supply. It should
     return a boolean value on whether it succeeded or not.
   \param arg2 An argument to supply to \a func.