From da098c3c681349076a468bb6eace911599fa0b7a Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Sun, 20 Dec 2009 23:01:31 +0000 Subject: [PATCH] Autogenerated HTML docs for v1.6.6-rc4 --- RelNotes-1.6.6.txt | 15 +++++---- technical/api-hash.html | 85 +++++++++++++++++++++++++++++++++++++++++++++-- technical/api-hash.txt | 50 ++++++++++++++++++++++++++-- technical/api-strbuf.html | 13 ++++++-- technical/api-strbuf.txt | 10 ++++-- 5 files changed, 156 insertions(+), 17 deletions(-) diff --git a/RelNotes-1.6.6.txt b/RelNotes-1.6.6.txt index b9e864238a..72df781e7d 100644 --- a/RelNotes-1.6.6.txt +++ b/RelNotes-1.6.6.txt @@ -22,10 +22,10 @@ These changes were discussed long time ago and existing behaviours have been identified as more problematic to the userbase than keeping them for the sake of backward compatibility. -When necessary, transition strategy for existing users has been designed +When necessary, a transition strategy for existing users has been designed not to force them running around setting configuration variables and updating their scripts in order to either keep the traditional behaviour -or adjust to the new behaviour on the day their sysadmin decides to install +or adjust to the new behaviour, on the day their sysadmin decides to install the new version of git. When we switched from "git-foo" to "git foo" in 1.6.0, even though the change had been advertised and the transition guide had been provided for a very long time, the users procrastinated @@ -34,11 +34,12 @@ their sysadmins updated their git installation. We are trying to avoid repeating that unpleasantness in the 1.7.0 release. For changes decided to be in 1.7.0, commands that will be affected -have been much louder to strongly discourage such procrastination. If -you have been using recent versions of git, you would have seen -warnings issued when you exercised features whose behaviour will -change, with a clear instruction on how to keep the existing behaviour -if you want to. You hopefully are already well prepared. +have been much louder to strongly discourage such procrastination, and +they continue to be in this release. If you have been using recent +versions of git, you would have seen warnings issued when you used +features whose behaviour will change, with a clear instruction on how +to keep the existing behaviour if you want to. You hopefully are +already well prepared. Of course, we have also been giving "this and that will change in 1.7.0; prepare yourselves" warnings in the release notes and diff --git a/technical/api-hash.html b/technical/api-hash.html index e2e4395fb1..b43a7ef0e2 100644 --- a/technical/api-hash.html +++ b/technical/api-hash.html @@ -311,13 +311,92 @@ div#toc a:visited { color: blue; }
-

Talk about <hash.h>

-

(Linus)

+

The hash API is a collection of simple hash table functions. Users are expected +to implement their own hashing.

+

Data Structures

+
+
+
+struct hash_table +
+
+

+ The hash table structure. The array member points to the hash table + entries. The size member counts the total number of valid and invalid + entries in the table. The nr member keeps track of the number of + valid entries. +

+
+
+struct hash_table_entry +
+
+

+ An opaque structure representing an entry in the hash table. The hash + member is the entry's hash key and the ptr member is the entry's + value. +

+
+
+
+

Functions

+
+
+
+init_hash +
+
+

+ Initialize the hash table. +

+
+
+free_hash +
+
+

+ Release memory associated with the hash table. +

+
+
+insert_hash +
+
+

+ Insert a pointer into the hash table. If an entry with that hash + already exists, a pointer to the existing entry's value is returned. + Otherwise NULL is returned. This allows callers to implement + chaining, etc. +

+
+
+lookup_hash +
+
+

+ Lookup an entry in the hash table. If an entry with that hash exists + the entry's value is returned. Otherwise NULL is returned. +

+
+
+for_each_hash +
+
+

+ Call a function for each entry in the hash table. The function is + expected to take the entry's value as its only argument and return an + int. If the function returns a negative int the loop is aborted + immediately. Otherwise, the return value is accumulated and the sum + returned upon completion of the loop. +

+
+
+
diff --git a/technical/api-hash.txt b/technical/api-hash.txt index c784d3edcb..e5061e0677 100644 --- a/technical/api-hash.txt +++ b/technical/api-hash.txt @@ -1,6 +1,52 @@ hash API ======== -Talk about +The hash API is a collection of simple hash table functions. Users are expected +to implement their own hashing. -(Linus) +Data Structures +--------------- + +`struct hash_table`:: + + The hash table structure. The `array` member points to the hash table + entries. The `size` member counts the total number of valid and invalid + entries in the table. The `nr` member keeps track of the number of + valid entries. + +`struct hash_table_entry`:: + + An opaque structure representing an entry in the hash table. The `hash` + member is the entry's hash key and the `ptr` member is the entry's + value. + +Functions +--------- + +`init_hash`:: + + Initialize the hash table. + +`free_hash`:: + + Release memory associated with the hash table. + +`insert_hash`:: + + Insert a pointer into the hash table. If an entry with that hash + already exists, a pointer to the existing entry's value is returned. + Otherwise NULL is returned. This allows callers to implement + chaining, etc. + +`lookup_hash`:: + + Lookup an entry in the hash table. If an entry with that hash exists + the entry's value is returned. Otherwise NULL is returned. + +`for_each_hash`:: + + Call a function for each entry in the hash table. The function is + expected to take the entry's value as its only argument and return an + int. If the function returns a negative int the loop is aborted + immediately. Otherwise, the return value is accumulated and the sum + returned upon completion of the loop. diff --git a/technical/api-strbuf.html b/technical/api-strbuf.html index c84f402069..464bd7533e 100644 --- a/technical/api-strbuf.html +++ b/technical/api-strbuf.html @@ -322,7 +322,7 @@ strbuf API actually relies on the string being free of NULs.

  1. -The buf member is never NULL, so you it can be used in any usual C +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.

    @@ -397,7 +397,7 @@ instead.

-

This is string buffer structure. The len member can be used to +

This is the string buffer structure. The len member can be used to determine the current length of the string, and buf member provides access to the string itself.

@@ -744,12 +744,19 @@ same behaviour as well. launch_editor
+

+ Launch the user preferred editor to edit a file and fill the buffer + with the file's contents upon the user completing their editing. The + third argument can be used to set the environment which the editor is + run in. If the buffer is NULL the editor is launched as usual but the + file's contents are not read into the buffer upon completion. +

diff --git a/technical/api-strbuf.txt b/technical/api-strbuf.txt index 7438149249..a0e0f850f8 100644 --- a/technical/api-strbuf.txt +++ b/technical/api-strbuf.txt @@ -12,7 +12,7 @@ strbuf API actually relies on the string being free of NULs. strbufs has some invariants that are very important to keep in mind: -. The `buf` member is never NULL, so you it can be used in any usual C +. 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. + @@ -55,7 +55,7 @@ Data structures * `struct strbuf` -This is string buffer structure. The `len` member can be used to +This is the string buffer structure. The `len` member can be used to determine the current length of the string, and `buf` member provides access to the string itself. @@ -253,3 +253,9 @@ same behaviour as well. comments are considered contents to be removed or not. `launch_editor`:: + + Launch the user preferred editor to edit a file and fill the buffer + with the file's contents upon the user completing their editing. The + third argument can be used to set the environment which the editor is + run in. If the buffer is NULL the editor is launched as usual but the + file's contents are not read into the buffer upon completion. -- 2.11.4.GIT