From 7bdd1f1898c6c94326e4642d8f51f74cc14b5f9d Mon Sep 17 00:00:00 2001
From: Felipe Oliveira Carvalho <felipekde@gmail.com>
Date: Sat, 29 Mar 2014 00:49:02 -0300
Subject: [PATCH] Document xmalloc() and deprecate lalloc()

---
 src/misc2.c | 18 +++++++++++++++---
 1 file changed, 15 insertions(+), 3 deletions(-)

diff --git a/src/misc2.c b/src/misc2.c
index 5c07ada005..143a106c40 100644
--- a/src/misc2.c
+++ b/src/misc2.c
@@ -647,8 +647,8 @@ char_u *lalloc_clear(long_u size, int message)
   return p;
 }
 
-/// When out of memory: try to release some memfile blocks and
-/// if some blocks are released call malloc again.
+/// Try to free memory. Used when trying to recover from out of memory errors.
+/// @see {xmalloc}
 void try_to_free_memory()
 {
   static bool trying_to_free = false;
@@ -667,6 +667,14 @@ void try_to_free_memory()
   trying_to_free = false;
 }
 
+/// malloc() wrapper
+///
+/// xmalloc() succeeds or gracefully aborts when out of memory.
+/// Before aborting try to free some memory and call malloc again.
+///
+/// @see {try_to_free_memory}
+/// @param size
+/// @return pointer to allocated space. Never NULL
 void *xmalloc(size_t size)
 {
   void *ret = malloc(size);
@@ -688,7 +696,11 @@ void *xmalloc(size_t size)
   return ret;
 }
 
-/// Old low level memory allocation function. Prefer xmalloc() from now on.
+/// Old low level memory allocation function.
+///
+/// @deprecated use xmalloc() directly instead
+/// @param size
+/// @return pointer to allocated space. Never NULL
 char_u *lalloc(long_u size, int message)
 {
   return (char_u *)xmalloc((size_t)size);