strbuf.h: drop asciidoc list formatting from API docs
Using a hanging indent is much more readable. This means we won't format as asciidoc anymore, but since we don't have a working system for extracting these comments anyway, it's probably more important to just make the source readable. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jeff King committed
Jan 16, 2015 at 04:05 UTC
aa07cac43fb03a01bcbcdffdaa49bf72a9eb06d1
1 file changed
+37
-37
strbuf.h
+37
-37
@@ -13,44 +13,44 @@
13
*
14
* strbufs have some invariants that are very important to keep in mind:
15
*
16
- * . The `buf` member is never NULL, so it can be used in any usual C
17
- * string operations safely. strbuf's _have_ to be initialized either by
18
- * `strbuf_init()` or by `= STRBUF_INIT` before the invariants, though.
19
- * +
20
- * Do *not* assume anything on what `buf` really is (e.g. if it is
21
- * allocated memory or not), use `strbuf_detach()` to unwrap a memory
22
- * buffer from its strbuf shell in a safe way. That is the sole supported
23
- * way. This will give you a malloced buffer that you can later `free()`.
24
- * +
25
- * However, it is totally safe to modify anything in the string pointed by
26
- * the `buf` member, between the indices `0` and `len-1` (inclusive).
16
+ * - The `buf` member is never NULL, so it can be used in any usual C
17
+ * string operations safely. strbuf's _have_ to be initialized either by
18
+ * `strbuf_init()` or by `= STRBUF_INIT` before the invariants, though.
19
*
28
- * . The `buf` member is a byte array that has at least `len + 1` bytes
29
- * allocated. The extra byte is used to store a `'\0'`, allowing the
30
- * `buf` member to be a valid C-string. Every strbuf function ensure this
31
- * invariant is preserved.
32
- * +
33
- * NOTE: It is OK to "play" with the buffer directly if you work it this
34
- * way:
35
- * +
36
- * ----
37
- * strbuf_grow(sb, SOME_SIZE); <1>
38
- * strbuf_setlen(sb, sb->len + SOME_OTHER_SIZE);
39
- * ----
40
- * <1> Here, the memory array starting at `sb->buf`, and of length
41
- * `strbuf_avail(sb)` is all yours, and you can be sure that
42
- * `strbuf_avail(sb)` is at least `SOME_SIZE`.
43
- * +
44
- * NOTE: `SOME_OTHER_SIZE` must be smaller or equal to `strbuf_avail(sb)`.
45
- * +
46
- * Doing so is safe, though if it has to be done in many places, adding the
47
- * missing API to the strbuf module is the way to go.
48
- * +
49
- * WARNING: Do _not_ assume that the area that is yours is of size `alloc
50
- * - 1` even if it's true in the current implementation. Alloc is somehow a
51
- * "private" member that should not be messed with. Use `strbuf_avail()`
52
- * instead.
53
- */
20
+ * Do *not* assume anything on what `buf` really is (e.g. if it is
21
+ * allocated memory or not), use `strbuf_detach()` to unwrap a memory
22
+ * buffer from its strbuf shell in a safe way. That is the sole supported
23
+ * way. This will give you a malloced buffer that you can later `free()`.
24
+ *
25
+ * However, it is totally safe to modify anything in the string pointed by
26
+ * the `buf` member, between the indices `0` and `len-1` (inclusive).
27
+ *
28
+ * - The `buf` member is a byte array that has at least `len + 1` bytes
29
+ * allocated. The extra byte is used to store a `'\0'`, allowing the
30
+ * `buf` member to be a valid C-string. Every strbuf function ensure this
31
+ * invariant is preserved.
32
+ *
33
+ * NOTE: It is OK to "play" with the buffer directly if you work it this
34
+ * way:
35
+ *
36
+ * ----
37
+ * strbuf_grow(sb, SOME_SIZE); <1>
38
+ * strbuf_setlen(sb, sb->len + SOME_OTHER_SIZE);
39
+ * ----
40
+ * <1> Here, the memory array starting at `sb->buf`, and of length
41
+ * `strbuf_avail(sb)` is all yours, and you can be sure that
42
+ * `strbuf_avail(sb)` is at least `SOME_SIZE`.
43
+ *
44
+ * NOTE: `SOME_OTHER_SIZE` must be smaller or equal to `strbuf_avail(sb)`.
45
+ *
46
+ * Doing so is safe, though if it has to be done in many places, adding the
47
+ * missing API to the strbuf module is the way to go.
48
+ *
49
+ * WARNING: Do _not_ assume that the area that is yours is of size `alloc
50
+ * - 1` even if it's true in the current implementation. Alloc is somehow a
51
+ * "private" member that should not be messed with. Use `strbuf_avail()`
52
+ * instead.
53
+*/
54
55
/**
56
* Data Structures