document the SkStrAppend methods

include/core/SkString.h

 
 /*
  * Copyright 2006 The Android Open Source Project
  *
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  */
 
 
 #ifndef SkString_DEFINED
@@ skipping 40 matching lines @@
     tmp[1] = '\0';
     return (-1 != SkStrFind(string, tmp));
 }
 
 static inline char *SkStrDup(const char string[]) {
     char *ret = (char *) sk_malloc_throw(strlen(string)+1);
     memcpy(ret,string,strlen(string)+1);
     return ret;
 }
 
-
+/*
+ *  The SkStrAppend... methods will write into the provided buffer, assuming it is large enough.
+ *  Each method has an associated const (e.g. SkStrAppendU32_MaxSize) which will be the largest
+ *  value needed for that method's buffer.
+ *
+ *  char storage[SkStrAppendU32_MaxSize];
+ *  SkStrAppendU32(storage, value);
+ *
+ *  Note : none of the SkStrAppend... methods write a terminating 0 to their buffers. Instead,
+ *  the methods return the ptr to the end of the written part of the buffer. This can be used
+ *  to compute the length, and/or know where to write a 0 if that is desired.
+ *
+ *  char storage[SkStrAppendU32_MaxSize + 1];
+ *  char* stop = SkStrAppendU32(storage, value);
+ *  size_t len = stop - storage;
+ *  *stop = 0;   // valid, since storage was 1 byte larger than the max.
+ */
 
 #define SkStrAppendU32_MaxSize  10
 char*   SkStrAppendU32(char buffer[], uint32_t);
 #define SkStrAppendU64_MaxSize  20
 char*   SkStrAppendU64(char buffer[], uint64_t, int minDigits);
 
 #define SkStrAppendS32_MaxSize  (SkStrAppendU32_MaxSize + 1)
 char*   SkStrAppendS32(char buffer[], int32_t);
 #define SkStrAppendS64_MaxSize  (SkStrAppendU64_MaxSize + 1)
 char*   SkStrAppendS64(char buffer[], int64_t, int minDigits);
@@ skipping 167 matching lines @@
 // Specialized to take advantage of SkString's fast swap path. The unspecialized function is
 // declared in SkTypes.h and called by SkTSort.
 template <> inline void SkTSwap(SkString& a, SkString& b) {
     a.swap(b);
 }
 
 // Split str on any characters in delimiters into out.  (Think, strtok with a sane API.)
 void SkStrSplit(const char* str, const char* delimiters, SkTArray<SkString>* out);
 
 #endif