From 3fd1d6b2f36722c64f8db77400c6f6a2639ebae0 Mon Sep 17 00:00:00 2001
From: Akim Demaille <akim@lrde.epita.fr>
Date: Tue, 25 Dec 2012 16:27:16 +0100
Subject: [PATCH 1/1] skeletons: factor comments about symbols

* data/variant.hh (b4_char_sizeof_): Rename as...
* data/bison.m4 (b4_symbol_tag_comment): this.
Provide more documentation about b4_symbol_*.
---
 data/bison.m4   | 40 +++++++++++++++++++++++++++++++++++++++-
 data/variant.hh |  9 +--------
 2 files changed, 40 insertions(+), 9 deletions(-)

diff --git a/data/bison.m4 b/data/bison.m4
index 26ef5c62..b6d9ed73 100644
--- a/data/bison.m4
+++ b/data/bison.m4
@@ -341,6 +341,33 @@ b4_define_flag_if([yacc])               # Whether POSIX Yacc is emulated.
 # macro per (token, field), where field can has_id, id, etc.: see
 # src/output.c:prepare_symbols_definitions().
 #
+# The various FIELDS are:
+#
+# - has_id: 0 or 1.
+#   Whether the symbol has an id.
+# - id: string
+#   If has_id, the id.  Guaranteed to be usable as a C identifier.
+# - tag: string.
+#   A representat of the symbol.  Can be 'foo', 'foo.id', '"foo"' etc.
+# - user_number: integer
+#   The assigned (external) number as used by yylex.
+# - is_token: 0 or 1
+#   Whether this is a terminal symbol.
+# - number: integer
+#   The internalized number (used after yytranslate).
+# - has_type: 0, 1
+#   Whether has a semantic value.
+# - type
+#   If it has a semantic value, its type tag, or, if variant are used,
+#   its type.
+# - has_printer: 0, 1
+# - printer: string
+# - printer_file: string
+# - printer_line: integer
+#   If the symbol has a printer, everything about it.
+# - has_destructor, destructor, destructor_file, destructor_line
+#   Likewise.
+#
 # The following macros provide access to these values.
 
 # b4_symbol_(NUM, FIELD)
@@ -354,7 +381,7 @@ m4_define([b4_symbol_],
 # b4_symbol(NUM, FIELD)
 # ---------------------
 # Recover a FIELD about symbol #NUM.  Thanks to m4_indir, fails if
-# undefined.  If FIELD = id, prepend the prefix.
+# undefined.  If FIELD = id, prepend the token prefix.
 m4_define([b4_symbol],
 [m4_case([$2],
          [id],    [m4_do([b4_percent_define_get([api.token.prefix])],
@@ -373,6 +400,14 @@ m4_define([b4_symbol_if],
          [m4_fatal([$0: field $2 of $1 is not a Boolean:] b4_symbol([$1], [$2]))])])
 
 
+# b4_symbol_tag_comment(SYMBOL-NUM)
+# ---------------------------------
+# Issue a comment giving the tag of symbol NUM.
+m4_define([b4_symbol_tag_comment],
+[b4_comment([b4_symbol([$1], [tag])])
+])
+
+
 # b4_symbol_action_location(SYMBOL-NUM, KIND)
 # -------------------------------------------
 # Report the location of the KIND action as FILE:LINE.
@@ -469,6 +504,9 @@ m4_define([b4_token_format],
 # ---------------------
 # Run actions for the symbol NUMS that all have the same type-name.
 # Skip NUMS that have no type-name.
+#
+# To specify the action to run, define b4_dollar_dollar(NUMBER,
+# TAG, TYPE).
 m4_define([b4_type_action_],
 [b4_symbol_if([$1], [has_type],
 [m4_map([b4_symbol_case_], [$@])[]dnl
diff --git a/data/variant.hh b/data/variant.hh
index 454f360a..1ebcfe80 100644
--- a/data/variant.hh
+++ b/data/variant.hh
@@ -51,13 +51,6 @@ m4_define([_b4_char_sizeof_dummy],
 dummy[]_b4_char_sizeof_counter])
 
 
-# b4_char_sizeof_(SYMBOL-NUM)
-# ---------------------------
-# A comment describing this symbol.
-m4_define([b4_char_sizeof_],
-[      // b4_symbol([$1], [tag])
-])
-
 # b4_char_sizeof(SYMBOL-NUMS)
 # ---------------------------
 # To be mapped on the list of type names to produce:
@@ -69,7 +62,7 @@ m4_define([b4_char_sizeof_],
 m4_define([b4_char_sizeof],
 [b4_symbol_if([$1], [has_type],
 [
-m4_map([b4_char_sizeof_], [$@])dnl
+m4_map([      b4_symbol_tag_comment], [$@])dnl
       char _b4_char_sizeof_dummy@{sizeof([b4_symbol([$1], [type])])@};
 ])])
 
-- 
2.45.2