Index: includes/common.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/common.inc,v
retrieving revision 1.994
diff -u -p -r1.994 common.inc
--- includes/common.inc	21 Sep 2009 07:56:07 -0000	1.994
+++ includes/common.inc	22 Sep 2009 21:20:57 -0000
@@ -10,6 +10,37 @@
  */
 
 /**
+ * @defgroup php_wrappers PHP wrapper functions
+ * @{
+ * Functions that are wrappers or custom implementations of PHP functions.
+ *
+ * Certain PHP functions should not be used in Drupal. Instead, Drupal's
+ * replacement functions should be used.
+ *
+ * For example, for improved or more secure UTF8-handling, or RFC-compliant
+ * handling of URLs in Drupal.
+ *
+ * For ease of use and memorizing, all these wrapper functions use the same name
+ * as the original PHP function, but prefixed with "drupal_". Beware, however,
+ * that not all wrapper functions support the same arguments as the original
+ * functions.
+ *
+ * You should always use these wrapper functions in your code.
+ *
+ * Wrong:
+ * @code
+ *   $my_substring = substr($original_string, 0, 5);
+ * @endcode
+ *
+ * Correct:
+ * @code
+ *   $my_substring = drupal_substr($original_string, 0, 5);
+ * @endcode
+ *
+ * @} End of "defgroup php_wrappers".
+ */
+
+/**
  * Error reporting level: display no errors.
  */
 define('ERROR_REPORTING_HIDE', 0);