From d2e152e6de738b85228f23fc575e1809b6702e8b Mon Sep 17 00:00:00 2001
From: Brion Vibber <brion@users.mediawiki.org>
Date: Thu, 28 Oct 2004 02:56:13 +0000
Subject: [PATCH] Munge doc comments. Mark as its own package for docs.

---
 includes/normal/Utf8Test.php          |  3 ++-
 includes/normal/UtfNormal.php         |  2 +-
 includes/normal/UtfNormalBench.php    |  6 +++--
 includes/normal/UtfNormalGenerate.php |  3 ++-
 includes/normal/UtfNormalTest.php     |  2 +-
 includes/normal/UtfNormalUtil.php     | 37 +++++++++++++++++++++++++--
 6 files changed, 45 insertions(+), 8 deletions(-)

diff --git a/includes/normal/Utf8Test.php b/includes/normal/Utf8Test.php
index 49d2f86a87..ba3555ea08 100644
--- a/includes/normal/Utf8Test.php
+++ b/includes/normal/Utf8Test.php
@@ -21,7 +21,8 @@
  * Runs the UTF-8 decoder test at:
  * http://www.cl.cam.ac.uk/~mgk25/ucs/examples/UTF-8-test.txt
  *
- * @package MediaWiki
+ * @package UtfNormal
+ * @access private
  */
 
 /** */
diff --git a/includes/normal/UtfNormal.php b/includes/normal/UtfNormal.php
index 862679988e..75e68a79f3 100644
--- a/includes/normal/UtfNormal.php
+++ b/includes/normal/UtfNormal.php
@@ -29,7 +29,7 @@
  *
  * See description of forms at http://www.unicode.org/reports/tr15/
  *
- * @package MediaWiki
+ * @package UtfNormal
  */
 
 /** */
diff --git a/includes/normal/UtfNormalBench.php b/includes/normal/UtfNormalBench.php
index d42d592099..f0355420d9 100644
--- a/includes/normal/UtfNormalBench.php
+++ b/includes/normal/UtfNormalBench.php
@@ -18,8 +18,10 @@
 # http://www.gnu.org/copyleft/gpl.html
 
 /**
- *
- * @package MediaWiki
+ * Approximate benchmark for some basic operations.
+ * 
+ * @package UtfNormal
+ * @access private
  */
 
 /** */
diff --git a/includes/normal/UtfNormalGenerate.php b/includes/normal/UtfNormalGenerate.php
index 436c918820..65128b706e 100644
--- a/includes/normal/UtfNormalGenerate.php
+++ b/includes/normal/UtfNormalGenerate.php
@@ -21,7 +21,8 @@
  * This script generates UniNormalData.inc from the Unicode Character Database
  * and supplementary files.
  *
- * @package MediaWiki 
+ * @package UtfNormal
+ * @access private
  */
 
 /** */
diff --git a/includes/normal/UtfNormalTest.php b/includes/normal/UtfNormalTest.php
index 16992be9fb..108bf5c6ac 100644
--- a/includes/normal/UtfNormalTest.php
+++ b/includes/normal/UtfNormalTest.php
@@ -20,7 +20,7 @@
 /**
  * Implements the conformance test at:
  * http://www.unicode.org/Public/UNIDATA/NormalizationTest.txt
- * @package MediaWiki
+ * @package UtfNormal
  */
 
 /** */
diff --git a/includes/normal/UtfNormalUtil.php b/includes/normal/UtfNormalUtil.php
index 039ac3c090..53f2c361f1 100644
--- a/includes/normal/UtfNormalUtil.php
+++ b/includes/normal/UtfNormalUtil.php
@@ -21,10 +21,20 @@
  * Some of these functions are adapted from places in MediaWiki.
  * Should probably merge them for consistency.
  *
- * @package MediaWiki
+ * @package UtfNormal
+ * @access public
  */
 
 /** */
+
+/**
+ * Return UTF-8 sequence for a given Unicode code point.
+ * May die if fed out of range data.
+ *
+ * @param int $codepoint
+ * @return string
+ * @access public
+ */
 function codepointToUtf8( $codepoint ) {
 	if($codepoint <		0x80) return chr($codepoint);
 	if($codepoint <    0x800) return chr($codepoint >>	6 & 0x3f | 0xc0) .
@@ -40,6 +50,15 @@ function codepointToUtf8( $codepoint ) {
 	die("Asked for code outside of range ($codepoint)\n");
 }
 
+/**
+ * Take a series of space-separated hexadecimal numbers representing
+ * Unicode code points and return a UTF-8 string composed of those
+ * characters. Used by UTF-8 data generation and testing routines.
+ *
+ * @param string $sequence
+ * @return string
+ * @access private
+ */
 function hexSequenceToUtf8( $sequence ) {
 	$utf = '';
 	foreach( explode( ' ', $sequence ) as $hex ) {
@@ -49,6 +68,14 @@ function hexSequenceToUtf8( $sequence ) {
 	return $utf;
 }
 
+/**
+ * Determine the Unicode codepoint of a single-character UTF-8 sequence.
+ * Does not check for invalid input data.
+ *
+ * @param string $char
+ * @return int
+ * @access public
+ */
 function utf8ToCodepoint( $char ) {
 	# Find the length
 	$z = ord( $char{0} );
@@ -79,10 +106,16 @@ function utf8ToCodepoint( $char ) {
 		$z |= ord( $char{$i} ) & 0x3f;
 	}
 
-	# Make entity
 	return $z;
 }
 
+/**
+ * Escape a string for inclusion in a PHP single-quoted string literal.
+ *
+ * @param string $string
+ * @return string
+ * @access public
+ */
 function escapeSingleString( $string ) {
 	return strtr( $string,
 		array(
-- 
2.20.1