mirror/ git
1
0
Fork 0
mirror of https://github.com/git/git.git synced 2024-05-21 17:26:09 +02:00
Code

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>
This commit is contained in:
Jeff King 2015-01-16 04:05:10 -05:00 committed by Junio C Hamano
parent 6afbbdda33
commit aa07cac43f
1 changed files with 37 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

74
strbuf.h
View File

@ -13,44 +13,44 @@
*
* strbufs have some invariants that are very important to keep in mind:
*
* . The `buf` member is never NULL, so it can be used in any usual C
* string operations safely. strbuf's _have_ to be initialized either by
* `strbuf_init()` or by `= STRBUF_INIT` before the invariants, though.
* +
* Do *not* assume anything on what `buf` really is (e.g. if it is
* allocated memory or not), use `strbuf_detach()` to unwrap a memory
* buffer from its strbuf shell in a safe way. That is the sole supported
* way. This will give you a malloced buffer that you can later `free()`.
* +
* However, it is totally safe to modify anything in the string pointed by
* the `buf` member, between the indices `0` and `len-1` (inclusive).
* - The `buf` member is never NULL, so it can be used in any usual C
* string operations safely. strbuf's _have_ to be initialized either by
* `strbuf_init()` or by `= STRBUF_INIT` before the invariants, though.
*
* . The `buf` member is a byte array that has at least `len + 1` bytes
* allocated. The extra byte is used to store a `'\0'`, allowing the
* `buf` member to be a valid C-string. Every strbuf function ensure this
* invariant is preserved.
* +
* NOTE: It is OK to "play" with the buffer directly if you work it this
* way:
* +
* ----
* strbuf_grow(sb, SOME_SIZE); <1>
* strbuf_setlen(sb, sb->len + SOME_OTHER_SIZE);
* ----
* <1> Here, the memory array starting at `sb->buf`, and of length
* `strbuf_avail(sb)` is all yours, and you can be sure that
* `strbuf_avail(sb)` is at least `SOME_SIZE`.
* +
* NOTE: `SOME_OTHER_SIZE` must be smaller or equal to `strbuf_avail(sb)`.
* +
* Doing so is safe, though if it has to be done in many places, adding the
* missing API to the strbuf module is the way to go.
* +
* WARNING: Do _not_ assume that the area that is yours is of size `alloc
* - 1` even if it's true in the current implementation. Alloc is somehow a
* "private" member that should not be messed with. Use `strbuf_avail()`
* instead.
*/
* Do *not* assume anything on what `buf` really is (e.g. if it is
* allocated memory or not), use `strbuf_detach()` to unwrap a memory
* buffer from its strbuf shell in a safe way. That is the sole supported
* way. This will give you a malloced buffer that you can later `free()`.
*
* However, it is totally safe to modify anything in the string pointed by
* the `buf` member, between the indices `0` and `len-1` (inclusive).
*
* - The `buf` member is a byte array that has at least `len + 1` bytes
* allocated. The extra byte is used to store a `'\0'`, allowing the
* `buf` member to be a valid C-string. Every strbuf function ensure this
* invariant is preserved.
*
* NOTE: It is OK to "play" with the buffer directly if you work it this
* way:
*
* ----
* strbuf_grow(sb, SOME_SIZE); <1>
* strbuf_setlen(sb, sb->len + SOME_OTHER_SIZE);
* ----
* <1> Here, the memory array starting at `sb->buf`, and of length
* `strbuf_avail(sb)` is all yours, and you can be sure that
* `strbuf_avail(sb)` is at least `SOME_SIZE`.
*
* NOTE: `SOME_OTHER_SIZE` must be smaller or equal to `strbuf_avail(sb)`.
*
* Doing so is safe, though if it has to be done in many places, adding the
* missing API to the strbuf module is the way to go.
*
* WARNING: Do _not_ assume that the area that is yours is of size `alloc
* - 1` even if it's true in the current implementation. Alloc is somehow a
* "private" member that should not be messed with. Use `strbuf_avail()`
* instead.
*/
/**
* Data Structures