strbuf: improve strbuf_get*line documentation
Clarify strbuf_getline() documentation, and add the missing documentation for strbuf_getwholeline() and strbuf_getwholeline_fd(). Signed-off-by: Thomas Rast <trast@student.ethz.ch> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Thomas Rast committed
Feb 23, 2012 at 10:42 UTC
1c5f93b9a69f4c1c3d09853243562b9ae3bf79a6
1 file changed
+17
-1
Documentation/technical/api-strbuf.txt
+17
-1
@@ -255,8 +255,24 @@ same behaviour as well.
255
256
`strbuf_getline`::
257
258
- Read a line from a FILE* pointer. The second argument specifies the line
258
+ Read a line from a FILE *, overwriting the existing contents
259
+ of the strbuf. The second argument specifies the line
260
terminator character, typically `'\n'`.
261
+ Reading stops after the terminator or at EOF. The terminator
262
+ is removed from the buffer before returning. Returns 0 unless
263
+ there was nothing left before EOF, in which case it returns `EOF`.
264
+
265
+`strbuf_getwholeline`::
266
+
267
+ Like `strbuf_getline`, but keeps the trailing terminator (if
268
+ any) in the buffer.
269
+
270
+`strbuf_getwholeline_fd`::
271
+
272
+ Like `strbuf_getwholeline`, but operates on a file descriptor.
273
+ It reads one character at a time, so it is very slow. Do not
274
+ use it unless you need the correct position in the file
275
+ descriptor.
276
277
`stripspace`::
278