tool/transcode_tablegen.rb: detailled documentation

for transcode_tblgen function [ci skip]

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@53115 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

ChangeLog

@@ -1,3 +1,8 @@
+Tue Dec 15 09:14:14 2015  Martin Duerst  <duerst@it.aoyama.ac.jp>
+
+	* tool/transcode_tablegen.rb: detailled documentation
+	  for transcode_tblgen function [ci skip]
+
 Mon Dec 14 22:11:11 2015  Martin Duerst  <duerst@it.aoyama.ac.jp>
 
 	* enc/ebcdic.h: new dummy encoding EBCDIC-US

tool/transcode-tblgen.rb

@@ -842,6 +842,43 @@ def transcode_tbl_only(from, to, map, valid_encoding=UnspecifiedValidEncoding)
   return map, tree_name, real_tree_name, max_input
 end
 
+#
+# call-seq:
+#   transcode_tblgen(from_name, to_name, map [, valid_encoding_check [, ascii_compatibility]]) -> ''
+#
+# Returns an empty string just in case the result is used somewhere.
+# Stores the actual product for later output with transcode_generated_code and
+# transcode_register_code.
+#
+# The first argument is a string that will be used for the source (from) encoding.
+# The second argument is a string that will be used for the target (to) encoding.
+#
+# The third argument is the actual data, a map represented as an array of two-element
+# arrays. Each element of the array stands for one character being converted. The
+# first element of each subarray is the code of the character in the source encoding,
+# the second element of each subarray is the code of the character in the target encoding.
+#
+# Each code (i.e. byte sequence) is represented as a string of hexadecimal characters
+# of even length. Codes can also be represented as integers (usually in the form Ox...),
+# in which case they are interpreted as Unicode codepoints encoded in UTF-8. So as
+# an example, 0x677E is the same as "E69DBE" (but somewhat easier to produce and check).
+#
+# In addition, the following symbols can also be used instead of actual codes in the
+# second element of a subarray:
+# :nomap (no mapping, just copy input to output), :nomap0 (same as :nomap, but low priority),
+# :undef (input code undefined in the destination encoding),
+# :invalid (input code is an invalid byte sequence in the source encoding),
+# :func_ii, :func_si, :func_io, :func_so (conversion by function with specific call
+# convention).
+# 
+# The forth argument specifies the overall structure of the encoding. For examples,
+# see ValidEncoding below. This is used to cross-check the data in the third argument
+# and to automatically add :undef and :invalid mappings where necessary.
+#
+# The fifth argument gives the ascii-compatibility of the transcoding. See
+# rb_transcoder_asciicompat_type_t in transcode_data.h for details. In most
+# cases, this argument can be left out.
+#
 def transcode_tblgen(from, to, map, valid_encoding=UnspecifiedValidEncoding,
                      ascii_compatibility='asciicompat_converter')
   map, tree_name, real_tree_name, max_input = transcode_tbl_only(from, to, map, valid_encoding)