cache: move doc to cache.h
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> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Heba Waly committed
Nov 17, 2019 at 21:04 UTC
13aa9c8b708dd65f32ac12f8b2faa48f5a89f07d
3 files changed
+39
-46
Documentation/MyFirstObjectWalk.txt
+2
-3
@@ -119,9 +119,8 @@ parameters provided by the user over the CLI.
119
120
`nr` represents the number of `rev_cmdline_entry` present in the array.
121
122
-`alloc` is used by the `ALLOC_GROW` macro. Check
123
-`Documentation/technical/api-allocation-growing.txt` - this variable is used to
124
-track the allocated size of the list.
122
+`alloc` is used by the `ALLOC_GROW` macro. Check `cache.h` - this variable is
123
+used to track the allocated size of the list.
124
125
Per entry, we find:
126
Documentation/technical/api-allocation-growing.txt
deleted
-39
@@ -1,39 +0,0 @@
1
-allocation growing API
2
-======================
3
-
4
-Dynamically growing an array using realloc() is error prone and boring.
5
-
6
-Define your array with:
7
-
8
-* a pointer (`item`) that points at the array, initialized to `NULL`
9
- (although please name the variable based on its contents, not on its
10
- type);
11
-
12
-* an integer variable (`alloc`) that keeps track of how big the current
13
- allocation is, initialized to `0`;
14
-
15
-* another integer variable (`nr`) to keep track of how many elements the
16
- array currently has, initialized to `0`.
17
-
18
-Then before adding `n`th element to the item, call `ALLOC_GROW(item, n,
19
-alloc)`. This ensures that the array can hold at least `n` elements by
20
-calling `realloc(3)` and adjusting `alloc` variable.
21
-
22
-------------
23
-sometype *item;
24
-size_t nr;
25
-size_t alloc
26
-
27
-for (i = 0; i < nr; i++)
28
- if (we like item[i] already)
29
- return;
30
-
31
-/* we did not like any existing one, so add one */
32
-ALLOC_GROW(item, nr + 1, alloc);
33
-item[nr++] = value you like;
34
-------------
35
-
36
-You are responsible for updating the `nr` variable.
37
-
38
-If you need to specify the number of elements to allocate explicitly
39
-then use the macro `REALLOC_ARRAY(item, alloc)` instead of `ALLOC_GROW`.
cache.h
+37
-4
@@ -632,10 +632,43 @@ int daemonize(void);
632
633
#define alloc_nr(x) (((x)+16)*3/2)
634
635
-/*
636
- * Realloc the buffer pointed at by variable 'x' so that it can hold
637
- * at least 'nr' entries; the number of entries currently allocated
638
- * is 'alloc', using the standard growing factor alloc_nr() macro.
635
+/**
636
+ * Dynamically growing an array using realloc() is error prone and boring.
637
+ *
638
+ * Define your array with:
639
+ *
640
+ * - a pointer (`item`) that points at the array, initialized to `NULL`
641
+ * (although please name the variable based on its contents, not on its
642
+ * type);
643
+ *
644
+ * - an integer variable (`alloc`) that keeps track of how big the current
645
+ * allocation is, initialized to `0`;
646
+ *
647
+ * - another integer variable (`nr`) to keep track of how many elements the
648
+ * array currently has, initialized to `0`.
649
+ *
650
+ * Then before adding `n`th element to the item, call `ALLOC_GROW(item, n,
651
+ * alloc)`. This ensures that the array can hold at least `n` elements by
652
+ * calling `realloc(3)` and adjusting `alloc` variable.
653
+ *
654
+ * ------------
655
+ * sometype *item;
656
+ * size_t nr;
657
+ * size_t alloc
658
+ *
659
+ * for (i = 0; i < nr; i++)
660
+ * if (we like item[i] already)
661
+ * return;
662
+ *
663
+ * // we did not like any existing one, so add one
664
+ * ALLOC_GROW(item, nr + 1, alloc);
665
+ * item[nr++] = value you like;
666
+ * ------------
667
+ *
668
+ * You are responsible for updating the `nr` variable.
669
+ *
670
+ * If you need to specify the number of elements to allocate explicitly
671
+ * then use the macro `REALLOC_ARRAY(item, alloc)` instead of `ALLOC_GROW`.
672
*
673
* Consider using ALLOC_GROW_BY instead of ALLOC_GROW as it has some
674
* added niceties.