git/strbuf.h, branch v2.4.2

strbuf.h: group documentation for trim functions

2015-01-16T22:40:47Z

The relationship between these makes more sense if you read them as a group, which can help people who are looking for the right function. Let's give them a single comment. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano

strbuf.h: drop boilerplate descriptions of strbuf_split_*

2015-01-16T22:40:47Z

The description of strbuf_split_buf says most of what needs to be said for all of the split variants that take strings, raw memory, etc. We have a boilerplate comment above each that points to the first. This boilerplate ends up making it harder to read, because it spaces out the functions, which could otherwise be read as a group. Let's drop the boilerplate completely, and mention the variants in the top comment. This is perhaps slightly worse for a hypothetical system which pulls the documentation for each function out of the comment immediately preceding it. But such a system does not yet exist, and anyway, the end result of extracting the boilerplate comments would not lead to a very easy-to-read result. We would do better in the long run to teach the extraction system about groups of related functions. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano

strbuf.h: reorganize api function grouping headers

2015-01-16T22:40:47Z

The original API doc had something like: Functions --------- * Life cycle ... some life-cycle functions ... * Related to the contents of the buffer ... functions related to contents .... etc This grouping can be hard to read in the comment sources, given the "*" in the comment lines, and the amount of text between each section. Instead, let's make a flat list of groupings, and underline each as a section header. That makes them stand out, and eliminates the weird half-phrase of "Related to...". Like: Functions related to the contents of the buffer ----------------------------------------------- Signed-off-by: Jeff King Signed-off-by: Junio C Hamano

strbuf.h: format asciidoc code blocks as 4-space indent

2015-01-16T22:40:47Z

This is much easier to read when the whole thing is stuffed inside a comment block. And there is precedent for this convention in markdown (and just in general ascii text). Signed-off-by: Jeff King Signed-off-by: Junio C Hamano

strbuf.h: drop asciidoc list formatting from API docs

2015-01-16T22:40:46Z

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 Signed-off-by: Junio C Hamano

strbuf.h: unify documentation comments beginnings

2015-01-16T22:40:46Z

The prior patch uses "/**" to denote "documentation" comments that we pulled from api-strbuf.txt. Let's use a consistent style for similar comments that were already in strbuf.h. Signed-off-by: Stefan Beller Signed-off-by: Jeff King Signed-off-by: Junio C Hamano

strbuf.h: integrate api-strbuf.txt documentation

2015-01-16T22:40:46Z

Some of strbuf is documented as comments above functions, and some is separate in Documentation/technical/api-strbuf.txt. This makes it annoying to find the appropriate documentation. We'd rather have it all in one place, which means all in the text document, or all in the header. Let's choose the header as that place. Even though the formatting is not quite as pretty, this keeps the documentation close to the related code. The hope is that this makes it easier to find what you want (human-readable comments are right next to the C declarations), and easier for writers to keep the documentation up to date. This is more or less a straight import of the text from api-strbuf.txt into C comments, complete with asciidoc formatting. The exceptions are: 1. All comments created in this way are started with "/**" to indicate they are part of the API documentation. This may help later with extracting the text to pretty-print it. 2. Function descriptions do not repeat the function name, as it is available in the context directly below. So: `strbuf_add`:: Add data of given length to the buffer. from api-strbuf.txt becomes: /** * Add data of given length to the buffer. */ void strbuf_add(struct strbuf *sb, const void *, size_t); As a result, any block-continuation required in asciidoc for that list item was dropped in favor of straight blank-line paragraph (since it is not necessary when we are not in a list item). 3. There is minor re-wording to integrate existing comments and api-strbuf text. In each case, I took whichever version was more descriptive, and eliminated any redundancies. In one case, for strbuf_addstr, the api documentation gave its inline definition; I eliminated this as redundant with the actual definition, which can be seen directly below the comment. 4. The functions in the header file are re-ordered to match the ordering of the API documentation, under the assumption that more thought went into the grouping there. Helped-by: Jonathan Nieder Signed-off-by: Jeff King Signed-off-by: Junio C Hamano

Merge branch 'rs/export-strbuf-addchars'

2014-09-19T18:38:39Z

Code clean-up. * rs/export-strbuf-addchars: strbuf: use strbuf_addchars() for adding a char multiple times strbuf: export strbuf_addchars()

strbuf: export strbuf_addchars()

2014-09-08T18:26:45Z

Move strbuf_addchars() to strbuf.c, where it belongs, and make it available for other callers. Signed-off-by: Rene Scharfe Signed-off-by: Junio C Hamano

Merge branch 'rs/strbuf-getcwd'

2014-09-02T20:28:44Z

Reduce the use of fixed sized buffer passed to getcwd() calls by introducing xgetcwd() helper. * rs/strbuf-getcwd: use strbuf_add_absolute_path() to add absolute paths abspath: convert absolute_path() to strbuf use xgetcwd() to set $GIT_DIR use xgetcwd() to get the current directory or die wrapper: add xgetcwd() abspath: convert real_path_internal() to strbuf abspath: use strbuf_getcwd() to remember original working directory setup: convert setup_git_directory_gently_1 et al. to strbuf unix-sockets: use strbuf_getcwd() strbuf: add strbuf_getcwd()