strbuf.h: remove a tad stale docs-in-comment and reference api-doc instead
Signed-off-by: Michael Witten <mfwitten@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Michael Witten committed
Feb 15, 2011 at 23:12 UTC
e0390119b249252a633875e4327c8a6463e4b6cb
1 file changed
+1
-36
strbuf.h
+1
-36
@@ -1,42 +1,7 @@
1
#ifndef STRBUF_H
2
#define STRBUF_H
3
4
-/*
5
- * Strbuf's can be use in many ways: as a byte array, or to store arbitrary
6
- * long, overflow safe strings.
7
- *
8
- * Strbufs has some invariants that are very important to keep in mind:
9
- *
10
- * 1. the ->buf member is always malloc-ed, hence strbuf's can be used to
11
- * build complex strings/buffers whose final size isn't easily known.
12
- *
13
- * It is NOT legal to copy the ->buf pointer away.
14
- * `strbuf_detach' is the operation that detaches a buffer from its shell
15
- * while keeping the shell valid wrt its invariants.
16
- *
17
- * 2. the ->buf member is a byte array that has at least ->len + 1 bytes
18
- * allocated. The extra byte is used to store a '\0', allowing the ->buf
19
- * member to be a valid C-string. Every strbuf function ensures this
20
- * invariant is preserved.
21
- *
22
- * Note that it is OK to "play" with the buffer directly if you work it
23
- * that way:
24
- *
25
- * strbuf_grow(sb, SOME_SIZE);
26
- * ... Here, the memory array starting at sb->buf, and of length
27
- * ... strbuf_avail(sb) is all yours, and you are sure that
28
- * ... strbuf_avail(sb) is at least SOME_SIZE.
29
- * strbuf_setlen(sb, sb->len + SOME_OTHER_SIZE);
30
- *
31
- * Of course, SOME_OTHER_SIZE must be smaller or equal to strbuf_avail(sb).
32
- *
33
- * Doing so is safe, though if it has to be done in many places, adding the
34
- * missing API to the strbuf module is the way to go.
35
- *
36
- * XXX: do _not_ assume that the area that is yours is of size ->alloc - 1
37
- * even if it's true in the current implementation. Alloc is somehow a
38
- * "private" member that should not be messed with.
39
- */
4
+/* See Documentation/technical/api-strbuf.txt */
5
6
#include <assert.h>
7