Merge r1611858, r1611908, r1611916 from trunk

doc: improve doxygen output for util_ebcdic.h and util_charset.h.

Submitted by: jailletc36
Reviewed by: jailletc36, rjung, ylavic
Backported by: jailletc36

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x@1635905 13f79535-47bb-0310-9956-ffa450edef68

diff --git a/STATUS b/STATUS
index 6979856715cb95ce0b2b30c60e6404787115ef32..d8574d9cdd5772c54034d733b647c180ce61d0b6 100644 (file)
--- a/STATUS
+++ b/STATUS
@@ -102,14 +102,6 @@ RELEASE SHOWSTOPPERS:
 PATCHES ACCEPTED TO BACKPORT FROM TRUNK:
   [ start all new proposals below, under PATCHES PROPOSED. ]
 
-   * doc: improve doxygen output for util_ebcdic.h and util_charset.h.
-     I propose it for vote because of the #if defined(DOXYGEN)
-     trunk patch: http://svn.apache.org/r1611858
-                  http://svn.apache.org/r1611908
-                  http://svn.apache.org/r1611916
-     2.4.x patch: trunk patch works
-     +1: jailletc36, rjung, ylavic
-
    * style fix
      trunk patch: http://svn.apache.org/r1633031
                   http://svn.apache.org/r1633522
@@ -220,7 +212,7 @@ PATCHES PROPOSED TO BACKPORT FROM TRUNK:
      2.4.x patch: trunk works
      +1 jkaluza
  
-    *core: Support custom ErrorDocuments for HTTP 501 and 414 status codes.
+   * core: Support custom ErrorDocuments for HTTP 501 and 414 status codes.
      PR 57167 
      trunk patch: http://svn.apache.org/r1635762
      2.4.x patch: trunk works

diff --git a/include/util_charset.h b/include/util_charset.h
index 0deb68f3977eb97f8226f03333194069650bb7b2..9df000d79528c6b0152bb41ab6768b3f981658c3 100644 (file)
--- a/include/util_charset.h
+++ b/include/util_charset.h
@@ -20,6 +20,16 @@
  *
  * @defgroup APACHE_CORE_CHARSET Charset Conversion
  * @ingroup  APACHE_CORE
+ * 
+ * These are the translation handles used to translate between the network
+ * format of protocol headers and the local machine format.
+ *
+ * For an EBCDIC machine, these are valid handles which are set up at
+ * initialization to translate between ISO-8859-1 and the code page of
+ * the source code.\n
+ * For an ASCII machine, they are undefined.
+ * 
+ * @see ap_init_ebcdic()
  * @{
  */
 
@@ -32,17 +42,24 @@ extern "C" {
 
 #include "apr.h"
 
-#if APR_CHARSET_EBCDIC
+#if APR_CHARSET_EBCDIC || defined(DOXYGEN)
 
 #include "apr_xlate.h"
 
-/** On EBCDIC machine this is a translation handle used to translate the
- *  headers from the local machine format to ASCII for network transmission.
- *  On an ASCII machine this is NULL */
+/**
+ * On EBCDIC machine this is a translation handle used to translate the
+ * headers from the local machine format to ASCII for network transmission.
+ * @note On ASCII system, this variable does <b>not</b> exist.
+ * So, its use should be guarded by \#if APR_CHARSET_EBCDIC.
+ */
 extern apr_xlate_t *ap_hdrs_to_ascii;
-/** On EBCDIC machine this is a translation handle used to translate the
- *  headers from ASCII to the local machine format after network transmission.
- *  On an ASCII machine this is NULL */
+
+/**
+ * On EBCDIC machine this is a translation handle used to translate the
+ * headers from ASCII to the local machine format after network transmission.
+ * @note On ASCII system, this variable does <b>not</b> exist.
+ * So, its use should be guarded by \#if APR_CHARSET_EBCDIC.
+ */
 extern apr_xlate_t *ap_hdrs_from_ascii;
 
 #endif  /* APR_CHARSET_EBCDIC */

diff --git a/include/util_ebcdic.h b/include/util_ebcdic.h
index fe35e418ad780f052a81b716402838d368da67fe..1457605677104e95ef171aea719b7f36d84238cf 100644 (file)
--- a/include/util_ebcdic.h
+++ b/include/util_ebcdic.h
@@ -35,35 +35,43 @@ extern "C" {
 #include "httpd.h"
 #include "util_charset.h"
 
-#if APR_CHARSET_EBCDIC
+#if APR_CHARSET_EBCDIC || defined(DOXYGEN)
 
 /**
- * Setup all of the global translation handlers
- * @param pool pool to allocate out of
+ * Setup all of the global translation handlers.
+ * @param   pool    The pool to allocate out of.
+ * @note On non-EBCDIC system, this function does <b>not</b> exist.
+ * So, its use should be guarded by \#if APR_CHARSET_EBCDIC.
  */
 apr_status_t ap_init_ebcdic(apr_pool_t *pool);
 
 /**
  * Convert protocol data from the implementation character
  * set to ASCII.
- * @param buffer buffer to translate
- * @param len number of bytes to translate
+ * @param   buffer  Buffer to translate.
+ * @param   len     Number of bytes to translate.
+ * @note On non-EBCDIC system, this function is replaced by an 
+ * empty macro.
  */
 void ap_xlate_proto_to_ascii(char *buffer, apr_size_t len);
 
 /**
  * Convert protocol data to the implementation character
  * set from ASCII.
- * @param buffer buffer to translate
- * @param len number of bytes to translate
+ * @param   buffer  Buffer to translate.
+ * @param   len     Number of bytes to translate.
+ * @note On non-EBCDIC system, this function is replaced by an 
+ * empty macro.
  */
 void ap_xlate_proto_from_ascii(char *buffer, apr_size_t len);
 
 /**
- * Convert protocol data from the implementation charater
+ * Convert protocol data from the implementation character
  * set to ASCII, then send it.
- * @param r   the current request
- * @param ... the strings to write, followed by a NULL pointer
+ * @param   r       The current request.
+ * @param   ...     The strings to write, followed by a NULL pointer.
+ * @note On non-EBCDIC system, this function is replaced by a call to
+ * #ap_rvputs.
  */
 int ap_rvputs_proto_in_ascii(request_rec *r, ...);
 

diff --git a/server/util_charset.c b/server/util_charset.c
index 514e0b43f3d6bfad31d7fc264e2faca43ae880f2..f896729a59ab3001402e9fc775075295dcd3efe9 100644 (file)
--- a/server/util_charset.c
+++ b/server/util_charset.c
@@ -23,20 +23,6 @@
 #include "http_core.h"
 #include "util_charset.h"
 
-/* ap_hdrs_to_ascii, ap_hdrs_from_ascii
- *
- * These are the translation handles used to translate between the network
- * format of protocol headers and the local machine format.
- *
- * For an EBCDIC machine, these are valid handles which are set up at
- * initialization to translate between ISO-8859-1 and the code page of
- * the source code.
- *
- * For an ASCII machine, these remain NULL so that when they are stored
- * in the BUFF via ap_bsetop(BO_RXLATE) it ensures that no translation is
- * performed.
- */
-
 apr_xlate_t *ap_hdrs_to_ascii, *ap_hdrs_from_ascii;
 
 #endif /*APR_CHARSET_EBCDIC */