[v3,12/21] cache: move doc to cache.h
diff mbox series

Message ID 1eca7099efeb6f57be646351d19baaf636a31b2b.1573507684.git.gitgitgadget@gmail.com
State New
Headers show
Series
  • Move doc to header files
Related show

Commit Message

Johannes Schindelin via GitGitGadget Nov. 11, 2019, 9:27 p.m. UTC
From: Heba Waly <heba.waly@gmail.com>

Move the documentation from Documentation/technical/api-allocation-growing.txt
to cache.h as it's easier for the developers to find the usage
information beside the code instead of looking for it in another doc file.

Also documentation/technical/api-allocation-growing.txt is removed because the
information it has is now redundant and it'll be hard to keep it up to
date and synchronized with the documentation in the header file.

Signed-off-by: Heba Waly <heba.waly@gmail.com>
---
 Documentation/MyFirstObjectWalk.txt           |  5 +--
 .../technical/api-allocation-growing.txt      | 39 ------------------
 cache.h                                       | 41 +++++++++++++++++--
 3 files changed, 39 insertions(+), 46 deletions(-)
 delete mode 100644 Documentation/technical/api-allocation-growing.txt

Comments

Junio C Hamano Nov. 12, 2019, 7:05 a.m. UTC | #1
> diff --git a/Documentation/MyFirstObjectWalk.txt b/Documentation/MyFirstObjectWalk.txt
> index 321c0ba6a4..6629122703 100644
> --- a/Documentation/MyFirstObjectWalk.txt
> +++ b/Documentation/MyFirstObjectWalk.txt
> @@ -119,9 +119,8 @@ parameters provided by the user over the CLI.
>  
>  `nr` represents the number of `rev_cmdline_entry` present in the array.
>  
> -`alloc` is used by the `ALLOC_GROW` macro. Check
> -`Documentation/technical/api-allocation-growing.txt` - this variable is used to
> -track the allocated size of the list.
> +`alloc` is used by the `ALLOC_GROW` macro. Check `cache.h` - this variable is 
> +used to track the allocated size of the list.

Trailing whitespace.
Heba Waly Nov. 14, 2019, 10:14 a.m. UTC | #2
On Tue, Nov 12, 2019 at 8:05 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> > diff --git a/Documentation/MyFirstObjectWalk.txt b/Documentation/MyFirstObjectWalk.txt
> > index 321c0ba6a4..6629122703 100644
> > --- a/Documentation/MyFirstObjectWalk.txt
> > +++ b/Documentation/MyFirstObjectWalk.txt
> > @@ -119,9 +119,8 @@ parameters provided by the user over the CLI.
> >
> >  `nr` represents the number of `rev_cmdline_entry` present in the array.
> >
> > -`alloc` is used by the `ALLOC_GROW` macro. Check
> > -`Documentation/technical/api-allocation-growing.txt` - this variable is used to
> > -track the allocated size of the list.
> > +`alloc` is used by the `ALLOC_GROW` macro. Check `cache.h` - this variable is
> > +used to track the allocated size of the list.
>
> Trailing whitespace.

Right, thanks!

Patch
diff mbox series

diff --git a/Documentation/MyFirstObjectWalk.txt b/Documentation/MyFirstObjectWalk.txt
index 321c0ba6a4..6629122703 100644
--- a/Documentation/MyFirstObjectWalk.txt
+++ b/Documentation/MyFirstObjectWalk.txt
@@ -119,9 +119,8 @@  parameters provided by the user over the CLI.
 
 `nr` represents the number of `rev_cmdline_entry` present in the array.
 
-`alloc` is used by the `ALLOC_GROW` macro. Check
-`Documentation/technical/api-allocation-growing.txt` - this variable is used to
-track the allocated size of the list.
+`alloc` is used by the `ALLOC_GROW` macro. Check `cache.h` - this variable is 
+used to track the allocated size of the list.
 
 Per entry, we find:
 
diff --git a/Documentation/technical/api-allocation-growing.txt b/Documentation/technical/api-allocation-growing.txt
deleted file mode 100644
index 5a59b54844..0000000000
--- a/Documentation/technical/api-allocation-growing.txt
+++ /dev/null
@@ -1,39 +0,0 @@ 
-allocation growing API
-======================
-
-Dynamically growing an array using realloc() is error prone and boring.
-
-Define your array with:
-
-* a pointer (`item`) that points at the array, initialized to `NULL`
-  (although please name the variable based on its contents, not on its
-  type);
-
-* an integer variable (`alloc`) that keeps track of how big the current
-  allocation is, initialized to `0`;
-
-* another integer variable (`nr`) to keep track of how many elements the
-  array currently has, initialized to `0`.
-
-Then before adding `n`th element to the item, call `ALLOC_GROW(item, n,
-alloc)`.  This ensures that the array can hold at least `n` elements by
-calling `realloc(3)` and adjusting `alloc` variable.
-
-------------
-sometype *item;
-size_t nr;
-size_t alloc
-
-for (i = 0; i < nr; i++)
-	if (we like item[i] already)
-		return;
-
-/* we did not like any existing one, so add one */
-ALLOC_GROW(item, nr + 1, alloc);
-item[nr++] = value you like;
-------------
-
-You are responsible for updating the `nr` variable.
-
-If you need to specify the number of elements to allocate explicitly
-then use the macro `REALLOC_ARRAY(item, alloc)` instead of `ALLOC_GROW`.
diff --git a/cache.h b/cache.h
index 04cabaac11..8fbbdf971a 100644
--- a/cache.h
+++ b/cache.h
@@ -632,10 +632,43 @@  int daemonize(void);
 
 #define alloc_nr(x) (((x)+16)*3/2)
 
-/*
- * Realloc the buffer pointed at by variable 'x' so that it can hold
- * at least 'nr' entries; the number of entries currently allocated
- * is 'alloc', using the standard growing factor alloc_nr() macro.
+/**
+ * Dynamically growing an array using realloc() is error prone and boring.
+ *
+ * Define your array with:
+ *
+ * - a pointer (`item`) that points at the array, initialized to `NULL`
+ *   (although please name the variable based on its contents, not on its
+ *   type);
+ *
+ * - an integer variable (`alloc`) that keeps track of how big the current
+ *   allocation is, initialized to `0`;
+ *
+ * - another integer variable (`nr`) to keep track of how many elements the
+ *   array currently has, initialized to `0`.
+ *
+ * Then before adding `n`th element to the item, call `ALLOC_GROW(item, n,
+ * alloc)`.  This ensures that the array can hold at least `n` elements by
+ * calling `realloc(3)` and adjusting `alloc` variable.
+ *
+ * ------------
+ * sometype *item;
+ * size_t nr;
+ * size_t alloc
+ *
+ * for (i = 0; i < nr; i++)
+ * 	if (we like item[i] already)
+ * 		return;
+ *
+ * // we did not like any existing one, so add one
+ * ALLOC_GROW(item, nr + 1, alloc);
+ * item[nr++] = value you like;
+ * ------------
+ *
+ * You are responsible for updating the `nr` variable.
+ *
+ * If you need to specify the number of elements to allocate explicitly
+ * then use the macro `REALLOC_ARRAY(item, alloc)` instead of `ALLOC_GROW`.
  *
  * Consider using ALLOC_GROW_BY instead of ALLOC_GROW as it has some
  * added niceties.