From dfe6cdda01b56ed4127c19a2a9e522055ce3ede4 Mon Sep 17 00:00:00 2001
From: marko <Unknown>
Date: Thu, 4 Jun 2009 05:58:23 +0000
Subject: [PATCH] branches/zip: Add Doxygen comments to the rest of buf0*.

---
 include/buf0buddy.h |  1 +
 include/buf0buf.h   | 22 +++++++++++++++++-----
 include/buf0lru.h   | 10 +++++-----
 include/buf0rea.h   |  8 +++++---
 4 files changed, 28 insertions(+), 13 deletions(-)

diff --git a/include/buf0buddy.h b/include/buf0buddy.h
index 7eb5a388af9..7648950d5d1 100644
--- a/include/buf0buddy.h
+++ b/include/buf0buddy.h
@@ -76,6 +76,7 @@ struct buf_buddy_stat_struct {
 	ib_uint64_t	relocated_usec;
 };
 
+/** Statistics of buddy blocks of a given size. */
 typedef struct buf_buddy_stat_struct buf_buddy_stat_t;
 
 /** Statistics of the buddy system, indexed by block size.
diff --git a/include/buf0buf.h b/include/buf0buf.h
index d3dd5e9661a..e0310992088 100644
--- a/include/buf0buf.h
+++ b/include/buf0buf.h
@@ -242,7 +242,7 @@ buf_page_get_known_nowait(
 Given a tablespace id and page number tries to get that page. If the
 page is not in the buffer pool it is not loaded and NULL is returned.
 Suitable for using when holding the kernel mutex. */
-
+UNIV_INTERN
 const buf_block_t*
 buf_page_try_get_func(
 /*==================*/
@@ -252,6 +252,12 @@ buf_page_try_get_func(
 	ulint		line,	/*!< in: line where called */
 	mtr_t*		mtr);	/*!< in: mini-transaction */
 
+/** Tries to get a page. If the page is not in the buffer pool it is
+not loaded.  Suitable for using when holding the kernel mutex.
+@param space_id	in: tablespace id
+@param page_no	in: page number
+@param mtr	in: mini-transaction
+@return		the page if in buffer pool, NULL if not */
 #define buf_page_try_get(space_id, page_no, mtr)	\
 	buf_page_try_get_func(space_id, page_no, __FILE__, __LINE__, mtr);
 
@@ -928,10 +934,16 @@ buf_pointer_is_block_field(
 /*=======================*/
 	const void*		ptr);	/*!< in: pointer not
 					dereferenced */
-#define buf_pool_is_block_mutex(m)	\
-		buf_pointer_is_block_field((void *)(m))
-#define buf_pool_is_block_lock(l)	\
-		buf_pointer_is_block_field((void *)(l))
+/** Find out if a pointer corresponds to a buf_block_t::mutex.
+@param m	in: mutex candidate
+@return		TRUE if m is a buf_block_t::mutex */
+#define buf_pool_is_block_mutex(m)			\
+	buf_pointer_is_block_field((const void*)(m))
+/** Find out if a pointer corresponds to a buf_block_t::lock.
+@param l	in: rw-lock candidate
+@return		TRUE if l is a buf_block_t::lock */
+#define buf_pool_is_block_lock(l)			\
+	buf_pointer_is_block_field((const void*)(l))
 
 #if defined UNIV_DEBUG || defined UNIV_ZIP_DEBUG
 /*********************************************************************//**
diff --git a/include/buf0lru.h b/include/buf0lru.h
index 32c61660d0f..463aca0982c 100644
--- a/include/buf0lru.h
+++ b/include/buf0lru.h
@@ -68,10 +68,10 @@ buf_LRU_buf_pool_running_out(void);
 These are low-level functions
 #########################################################################*/
 
-/* Minimum LRU list length for which the LRU_old pointer is defined */
-
+/** Minimum LRU list length for which the LRU_old pointer is defined */
 #define BUF_LRU_OLD_MIN_LEN	80
 
+/** Maximum LRU list search length in buf_flush_LRU_recommendation() */
 #define BUF_LRU_FREE_SEARCH_LEN		(5 + 2 * BUF_READ_AHEAD_AREA)
 
 /******************************************************************//**
@@ -227,18 +227,18 @@ buf_LRU_print(void);
 /*===============*/
 #endif /* UNIV_DEBUG_PRINT || UNIV_DEBUG || UNIV_BUF_DEBUG */
 
-/******************************************************************//**
+/** @brief Statistics for selecting the LRU list for eviction.
+
 These statistics are not 'of' LRU but 'for' LRU.  We keep count of I/O
 and page_zip_decompress() operations.  Based on the statistics we decide
 if we want to evict from buf_pool->unzip_LRU or buf_pool->LRU. */
-
-/** Statistics for selecting the LRU list for eviction. */
 struct buf_LRU_stat_struct
 {
 	ulint	io;	/**< Counter of buffer pool I/O operations. */
 	ulint	unzip;	/**< Counter of page_zip_decompress operations. */
 };
 
+/** Statistics for selecting the LRU list for eviction. */
 typedef struct buf_LRU_stat_struct buf_LRU_stat_t;
 
 /** Current operation counters.  Not protected by any mutex.
diff --git a/include/buf0rea.h b/include/buf0rea.h
index 781f99f2fa3..b4d25e6fde0 100644
--- a/include/buf0rea.h
+++ b/include/buf0rea.h
@@ -124,14 +124,16 @@ buf_read_recv_pages(
 	ulint		n_stored);	/*!< in: number of page numbers
 					in the array */
 
-/* The size in pages of the area which the read-ahead algorithms read if
+/** The size in pages of the area which the read-ahead algorithms read if
 invoked */
-
 #define	BUF_READ_AHEAD_AREA					\
 	ut_min(64, ut_2_power_up(buf_pool->curr_size / 32))
 
-/* Modes used in read-ahead */
+/** @name Modes used in read-ahead @{ */
+/** read only pages belonging to the insert buffer tree */
 #define BUF_READ_IBUF_PAGES_ONLY	131
+/** read any page */
 #define BUF_READ_ANY_PAGE		132
+/* @} */
 
 #endif