Improve doxygen comment.

Improve layout, fix typo, generate relevant doc even if build on non-EBCDIC system + add note that these functions are mostly noop on non-EBCDIC system.

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1611858 13f79535-47bb-0310-9956-ffa450edef68

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, ...);