style: fix comments

[bison.git] / src / muscle-tab.h

diff --git a/src/muscle-tab.h b/src/muscle-tab.h
index 7eff4f5a9e60c01b543a267cd789cf99dfd797e7..30a74523c3bbbf42ed243c2ccbac7eba9b8dfd91 100644 (file)
--- a/src/muscle-tab.h
+++ b/src/muscle-tab.h
@@ -1,6 +1,6 @@
 /* Muscle table manager for Bison,
 
-   Copyright (C) 2001-2003, 2006-2012 Free Software Foundation, Inc.
+   Copyright (C) 2001-2003, 2006-2013 Free Software Foundation, Inc.
 
    This file is part of Bison, the GNU Compiler Compiler.
 
@@ -24,62 +24,72 @@
 
 # include "location.h"
 
+/* Create the MUSCLE_TABLE, and initialize it with default values.
+   Also set up the MUSCLE_OBSTACK.  */
 void muscle_init (void);
+
+/* Insert (KEY, VALUE).  If KEY already existed, overwrite the
+   previous value.  */
 void muscle_insert (char const *key, char const *value);
+
+/* Find the value of muscle KEY.  Unlike MUSCLE_FIND, this is always
+   reliable to determine whether KEY has a value.  */
 char const *muscle_find_const (char const *key);
+
+/* Find the value of muscle KEY.  Abort if muscle_insert was invoked
+   more recently than muscle_grow for KEY since muscle_find can't
+   return a char const *.  */
 char *muscle_find (char const *key);
+
+/* Free all the memory consumed by the muscle machinery only.  */
 void muscle_free (void);
 
 
 /* An obstack dedicated to receive muscle keys and values.  */
 extern struct obstack muscle_obstack;
 
-#define MUSCLE_INSERT_BOOL(Key, Value)                          \
-  do {                                                          \
-    int v__ = Value;                                            \
-    MUSCLE_INSERT_INT (Key, v__);                               \
+# define MUSCLE_INSERT_BOOL(Key, Value)         \
+  do {                                          \
+    int v__ = Value;                            \
+    MUSCLE_INSERT_INT (Key, v__);               \
   } while (0)
 
-#define MUSCLE_INSERTF(Key, Format, Value)                      \
+# define MUSCLE_INSERTF(Key, Format, Value)                     \
   do {                                                          \
     obstack_printf (&muscle_obstack, Format, Value);            \
     muscle_insert (Key, obstack_finish0 (&muscle_obstack));     \
   } while (0)
 
-#define MUSCLE_INSERT_INT(Key, Value)                           \
+# define MUSCLE_INSERT_INT(Key, Value)          \
   MUSCLE_INSERTF(Key, "%d", Value)
 
-#define MUSCLE_INSERT_LONG_INT(Key, Value)                      \
+# define MUSCLE_INSERT_LONG_INT(Key, Value)     \
   MUSCLE_INSERTF(Key, "%ld", Value)
 
 /* Key -> Value, but don't apply escaping to Value. */
-#define MUSCLE_INSERT_STRING_RAW(Key, Value)                    \
+# define MUSCLE_INSERT_STRING_RAW(Key, Value)   \
   MUSCLE_INSERTF(Key, "%s", Value)
 
 /* Key -> Value, applying M4 escaping to Value. */
-#define MUSCLE_INSERT_STRING(Key, Value)                        \
+# define MUSCLE_INSERT_STRING(Key, Value)                       \
   do {                                                          \
     obstack_escape (&muscle_obstack, Value);                    \
     muscle_insert (Key, obstack_finish0 (&muscle_obstack));     \
   } while (0)
 
-#define MUSCLE_INSERT_C_STRING(Key, Value)                      \
-  do {                                                          \
-    obstack_escape (&muscle_obstack,                            \
-                    quotearg_style (c_quoting_style, Value));   \
-    muscle_insert (Key, obstack_finish0 (&muscle_obstack));     \
-  } while (0)
+/* Key -> Value, applying C escaping to Value (and then M4). */
+# define MUSCLE_INSERT_C_STRING(Key, Value)                     \
+  MUSCLE_INSERT_STRING(Key, quotearg_style (c_quoting_style, Value))
+
 
 /* Append VALUE to the current value of KEY.  If KEY did not already
    exist, create it.  Use MUSCLE_OBSTACK.  De-allocate the previously
    associated value.  Copy VALUE and SEPARATOR.  */
-
 void muscle_grow (const char *key, const char *value, const char *separator);
 
 
 /* Append VALUE to the current value of KEY, using muscle_grow.  But
    in addition, issue a synchronization line for the location LOC.  */
-
 void muscle_code_grow (const char *key, const char *value, location loc);
 
 
@@ -92,14 +102,15 @@ void muscle_pair_list_grow (const char *muscle,
 
 /* Grow KEY for the occurrence of the name USER_NAME at LOC appropriately for
    use with b4_check_user_names in ../data/bison.m4.  USER_NAME is not escaped
-   with digraphs, so it must not contain `[' or `]'.  */
+   with digraphs, so it must not contain '[' or ']'.  */
 void muscle_user_name_list_grow (char const *key, char const *user_name,
                                  location loc);
 
 /* Indicates whether a variable's value was specified with -D/--define, with
    -F/--force-define, or in the grammar file.  */
 typedef enum {
-  MUSCLE_PERCENT_DEFINE_D = 0, MUSCLE_PERCENT_DEFINE_F,
+  MUSCLE_PERCENT_DEFINE_D = 0,
+  MUSCLE_PERCENT_DEFINE_F,
   MUSCLE_PERCENT_DEFINE_GRAMMAR_FILE
 } muscle_percent_define_how;
 
@@ -186,6 +197,8 @@ void muscle_percent_define_check_values (char const * const *values);
 void muscle_percent_code_grow (char const *qualifier, location qualifier_loc,
                                char const *code, location code_loc);
 
+/* Output the definition of all the current muscles into a list of
+   m4_defines.  */
 void muscles_m4_output (FILE *out);
 
 #endif /* not MUSCLE_TAB_H_ */