diff options
| author | Jonathan Nieder <jrnieder@gmail.com> | 2014-12-09 14:49:50 -0800 |
|---|---|---|
| committer | Junio C Hamano <gitster@pobox.com> | 2014-12-10 14:32:19 -0800 |
| commit | a90c70721ac9b0046adac7507d56c24b5bcfda4f (patch) | |
| tree | f3d40e9aaab2ec4018396c8636a88d4985abc9e5 /Documentation/technical | |
| parent | 1a6f946687b74803550d2e0beb3eaf2e6ab60357 (diff) | |
| download | git-jn/dedup-doc-header.tar.gz | |
put string-list API documentation in one placejn/dedup-doc-header
Until recently (v1.8.0-rc0~46^2~5, 2012-09-12), the string-list API
was documented in detail in Documentation/technical/api-string-list.txt
and the header file contained section markers and some short reminders
but little other documentation.
Since then, the header has acquired some more comments that are mostly
identical to the documentation from technical/. In principle that
should help convenience, since it means one less hop for someone
reading the header to find API documentation. In practice,
unfortunately, it is hard to remember that there is documentation in
two places, and the comprehensive documentation of some functions in
the header makes it too easy to forget that the other functions are
documented at all (and where).
Add a comment pointing to Documentation/technical/ and remove the
comments that duplicate what is written there. Longer term, we may
want to move all of the technical docs to header files and generate
printer-ready API documentation another way, but that is a larger
change for another day.
Short reminders in the header file are still okay.
Reported-by: Stefan Beller <sbeller@google.com>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Diffstat (limited to 'Documentation/technical')
| -rw-r--r-- | Documentation/technical/api-string-list.txt | 12 |
1 files changed, 11 insertions, 1 deletions
diff --git a/Documentation/technical/api-string-list.txt b/Documentation/technical/api-string-list.txt index d51a6579c8..a85e71360d 100644 --- a/Documentation/technical/api-string-list.txt +++ b/Documentation/technical/api-string-list.txt @@ -185,7 +185,17 @@ overwriting the delimiter characters with NULs and creating new string_list_items that point into the original string (the original string must therefore not be modified or freed while the `string_list` is in use). - ++ +Examples: ++ +---- +string_list_split(l, "foo:bar:baz", ':', -1) -> ["foo", "bar", "baz"] +string_list_split(l, "foo:bar:baz", ':', 0) -> ["foo:bar:baz"] +string_list_split(l, "foo:bar:baz", ':', 1) -> ["foo", "bar:baz"] +string_list_split(l, "foo:bar:", ':', -1) -> ["foo", "bar", ""] +string_list_split(l, "", ':', -1) -> [""] +string_list_split(l, ":", ':', -1) -> ["", ""] +---- Data structures --------------- |