From 5c42dd02ed77a12545aa4e95a5773150e8b03984 Mon Sep 17 00:00:00 2001
From: "Steven R. Loomis" <srl@icu-project.org>
Date: Wed, 2 Nov 2011 23:53:18 +0000
Subject: [PATCH] ICU-8862 add doxygen snippet and a couple of samples

X-SVN-Rev: 30906
---
 icu4c/source/Doxyfile.in               |  2 +-
 icu4c/source/common/unicode/ucnv.h     | 31 ++------------------
 icu4c/source/samples/ucnv/convsamp.cpp | 40 ++++++++++++++++++++++++++
 3 files changed, 44 insertions(+), 29 deletions(-)

diff --git a/icu4c/source/Doxyfile.in b/icu4c/source/Doxyfile.in
index 9600f8f5b0..a6cd982025 100644
--- a/icu4c/source/Doxyfile.in
+++ b/icu4c/source/Doxyfile.in
@@ -92,7 +92,7 @@ RECURSIVE              = NO
 EXCLUDE                = @srcdir@/common/unicode/urename.h @srcdir@/common/unicode/udraft.h @srcdir@/common/unicode/udeprctd.h @srcdir@/common/unicode/uobslete.h @srcdir@/common/unicode/ppalmos.h  
 EXCLUDE_SYMLINKS       = NO
 EXCLUDE_PATTERNS       = config*.h
-EXAMPLE_PATH           = 
+EXAMPLE_PATH           = @srcdir@/
 EXAMPLE_PATTERNS       = 
 EXAMPLE_RECURSIVE      = NO
 IMAGE_PATH             = 
diff --git a/icu4c/source/common/unicode/ucnv.h b/icu4c/source/common/unicode/ucnv.h
index 4a23addf4b..daf37cccf5 100644
--- a/icu4c/source/common/unicode/ucnv.h
+++ b/icu4c/source/common/unicode/ucnv.h
@@ -341,6 +341,8 @@ ucnv_compareNames(const char *name1, const char *name2);
  * other than its an alias starting with the letters "cp". Please do not
  * associate any meaning to these aliases.</p>
  *
+ * \snippet samples/ucnv/convsamp.cpp ucnv_open
+ *
  * @param converterName Name of the coded character set table.
  *          This may have options appended to the string.
  *          IANA alias character set names, IBM CCSIDs starting with "ibm-",
@@ -1956,34 +1958,7 @@ ucnv_usesFallback(const UConverter *cnv);
  * instead of the input signature bytes.
  * <p>
  * Usage:
- * @code     
- *      UErrorCode err = U_ZERO_ERROR;
- *      char input[] = { '\xEF','\xBB', '\xBF','\x41','\x42','\x43' };
- *      int32_t signatureLength = 0;
- *      char *encoding = ucnv_detectUnicodeSignature(input,sizeof(input),&signatureLength,&err);
- *      UConverter *conv = NULL;
- *      UChar output[100];
- *      UChar *target = output, *out;
- *      char *source = input;
- *      if(encoding!=NULL && U_SUCCESS(err)){
- *          // should signature be discarded ?
- *          conv = ucnv_open(encoding, &err);
- *          // do the conversion
- *          ucnv_toUnicode(conv,
- *                         target, output + sizeof(output)/U_SIZEOF_UCHAR,
- *                         source, input + sizeof(input),
- *                         NULL, TRUE, &err);
- *          out = output;
- *          if (discardSignature){
- *              ++out; // ignore initial U+FEFF
- *          }
- *          while(out != target) {
- *              printf("%04x ", *out++);
- *          }
- *          puts("");
- *      }
- *     
- * @endcode
+ * \snippet samples/ucnv/convsamp.cpp ucnv_detectUnicodeSignature
  *
  * @param source            The source string in which the signature should be detected.
  * @param sourceLength      Length of the input string, or -1 if terminated with a NUL byte.
diff --git a/icu4c/source/samples/ucnv/convsamp.cpp b/icu4c/source/samples/ucnv/convsamp.cpp
index 93cd4d2a86..38b9c28e15 100644
--- a/icu4c/source/samples/ucnv/convsamp.cpp
+++ b/icu4c/source/samples/ucnv/convsamp.cpp
@@ -212,7 +212,9 @@ UErrorCode convsample_02()
   int32_t     len;
 
   // set up the converter
+  //! [ucnv_open]
   conv = ucnv_open("koi8-r", &status);
+  //! [ucnv_open]
   assert(U_SUCCESS(status));
 
   // convert to koi8-r
@@ -1073,6 +1075,42 @@ UErrorCode convsample_46()
 
 #define BUFFERSIZE 219
 
+void convsample_50() {
+  printf("\n\n==============================================\n"
+         "Sample 50: C: ucnv_detectUnicodeSignature\n");
+
+  //! [ucnv_detectUnicodeSignature]
+  UErrorCode err = U_ZERO_ERROR;
+  UBool discardSignature = TRUE; /* set to TRUE to throw away the initial U+FEFF */
+  char input[] = { '\xEF','\xBB', '\xBF','\x41','\x42','\x43' };
+  int32_t signatureLength = 0;
+  const char *encoding = ucnv_detectUnicodeSignature(input,sizeof(input),&signatureLength,&err);
+  UConverter *conv = NULL;
+  UChar output[100];
+  UChar *target = output, *out;
+  const char *source = input;
+  if(encoding!=NULL && U_SUCCESS(err)){
+    // should signature be discarded ?
+    conv = ucnv_open(encoding, &err);
+    // do the conversion
+    ucnv_toUnicode(conv,
+                   &target, output + sizeof(output)/U_SIZEOF_UCHAR,
+                   &source, input + sizeof(input),
+                   NULL, TRUE, &err);
+    out = output;
+    if (discardSignature){
+      ++out; // ignore initial U+FEFF
+    }
+    while(out != target) {
+      printf("%04x ", *out++);
+    }
+    puts("");
+  }
+  //! [ucnv_detectUnicodeSignature]
+  puts("");
+}
+
+
 
 /* main */
 
@@ -1096,6 +1134,8 @@ int main()
   convsample_40();  // C,   cp37 -> UTF16 [data02.bin -> data40.utf16]
   
   convsample_46();  // C,  UTF16 -> latin3 [data41.utf16 -> data46.out]
+
+  convsample_50();  // C, detect unicode signature
   
   printf("End of converter samples.\n");