Patch from Paul for additional documentation of api.

Updated based on feedback, and to apply to 2.6.8-rc3.  I will be adding more
detailed documentation to the Documentation directory in a separate patch.
Signed-off-by: Paul McKenney <paulmck@us.ibm.com>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>