Index: assoc.h =================================================================== RCS file: /sources/bison/bison/src/assoc.h,v retrieving revision 1.5 diff -u -r1.5 assoc.h --- assoc.h 9 Mar 2006 23:23:10 -0000 1.5 +++ assoc.h 1 Jul 2006 13:26:45 -0000 @@ -17,11 +17,15 @@ along with Bison; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. */ +/** + * \file assoc.h + * \brief Defining :: associativity. + */ #ifndef ASSOC_H_ # define ASSOC_H_ -/* Associativity values for tokens and rules. */ +/** Associativity values for tokens and rules.*/ typedef enum { undef_assoc, Index: derives.h =================================================================== RCS file: /sources/bison/bison/src/derives.h,v retrieving revision 1.9 diff -u -r1.9 derives.h --- derives.h 14 May 2005 06:49:47 -0000 1.9 +++ derives.h 1 Jul 2006 13:26:45 -0000 @@ -1,6 +1,6 @@ /* Match rules with nonterminals for bison, - Copyright (C) 1984, 1989, 2000, 2001, 2002 Free Software + Copyright (C) 1984, 1989, 2000, 2001, 2002, 2006 Free Software Foundation, Inc. This file is part of Bison, the GNU Compiler Compiler. @@ -19,17 +19,21 @@ along with Bison; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. */ - +/** + * \file derives.h + * \brief Match rules with non-terminals. + */ #ifndef DERIVES_H_ # define DERIVES_H_ # include "gram.h" -/* DERIVES[SYMBOL - NTOKENS] points to a vector of the rules that - SYMBOL derives, terminated with NULL. */ +/** DERIVES[SYMBOL - NTOKENS] points to a vector of the rules that + * SYMBOL derives, terminated with NULL. + */ extern rule ***derives; -/* Compute DERIVES. */ +/** Compute DERIVES. */ void derives_compute (void); void derives_free (void); Index: gram.h =================================================================== RCS file: /sources/bison/bison/src/gram.h,v retrieving revision 1.59 diff -u -r1.59 gram.h --- gram.h 6 Jun 2006 16:40:06 -0000 1.59 +++ gram.h 1 Jul 2006 13:26:45 -0000 @@ -1,3 +1,4 @@ + /* Data definitions for internal representation of Bison's input. Copyright (C) 1984, 1986, 1989, 1992, 2001, 2002, 2003, 2004, 2005, 2006 @@ -20,90 +21,96 @@ the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. */ +/** + * \file gram.h + * \brief Definitions for internal representation of Bison's input grammar. + */ + +/** + * Representation of the grammar rules: + * + * NTOKENS is the number of tokens, and NVARS is the number of + * variables (nonterminals). NSYMS is the total number, ntokens + + * nvars. + * + * Each symbol (either token or variable) receives a symbol number. + * Numbers 0 to NTOKENS - 1 are for tokens, and NTOKENS to NSYMS - 1 + * are for variables. Symbol number zero is the end-of-input token. + * This token is counted in ntokens. The true number of token values + * assigned is NTOKENS reduced by one for each alias declaration. + * + * The rules receive rule numbers 1 to NRULES in the order they are + * written. More precisely Bison augments the grammar with the + * initial rule, `$accept: START-SYMBOL $end', which is numbered 1, + * all the user rules are 2, 3 etc. Each time a rule number is + * presented to the user, we subtract 1, so *displayed* rule numbers + * are 0, 1, 2... + * + * Internally, we cannot use the number 0 for a rule because for + * instance RITEM stores both symbol (the RHS) and rule numbers: the + * symbols are shorts >= 0, and rule number are stored negative. + * Therefore 0 cannot be used, since it would be both the rule number + * 0, and the token $end). + * + * Actions are accessed via the rule number. + * + * The rules themselves are described by several arrays: amongst which + * RITEM, and RULES. + * + * RULES is an array of rules, whose members are: + * + * RULES[R].lhs -- the symbol of the left hand side of rule R. + * + * RULES[R].rhs -- the index in RITEM of the beginning of the portion + * for rule R. + * + * RULES[R].prec -- the symbol providing the precedence level of R. + * + * RULES[R].precsym -- the symbol attached (via %prec) to give its + * precedence to R. Of course, if set, it is equal to `prec', but we + * need to distinguish one from the other when reducing: a symbol used + * in a %prec is not useless. + * + * RULES[R].assoc -- the associativity of R. + * + * RULES[R].dprec -- the dynamic precedence level of R (for GLR + * parsing). + * + * RULES[R].merger -- index of merging function for R (for GLR + * parsing). + * + * RULES[R].line -- the line where R was defined. + * + * RULES[R].useful -- true iff the rule is used (i.e., false if thrown + * away by reduce). + * + * The right hand side is stored as symbol numbers in a portion of + * RITEM. + * + * The length of the portion is one greater than the number of symbols + * in the rule's right hand side. The last element in the portion + * contains minus R, which identifies it as the end of a portion and + * says which rule it is for. + * + * The portions of RITEM come in order of increasing rule number. + * NRITEMS is the total length of RITEM. Each element of RITEM is + * called an "item" and its index in RITEM is an item number. + * + * Item numbers are used in the finite state machine to represent + * places that parsing can get to. + * + * SYMBOLS[I]->prec records the precedence level of each symbol. + * + * Precedence levels are assigned in increasing order starting with 1 + * so that numerically higher precedence values mean tighter binding + * as they ought to. Zero as a symbol or rule's precedence means none + * is assigned. + * + * Associativities are recorded similarly in SYMBOLS[I]->assoc. + */ #ifndef GRAM_H_ # define GRAM_H_ -/* Representation of the grammar rules: - - NTOKENS is the number of tokens, and NVARS is the number of - variables (nonterminals). NSYMS is the total number, ntokens + - nvars. - - Each symbol (either token or variable) receives a symbol number. - Numbers 0 to NTOKENS - 1 are for tokens, and NTOKENS to NSYMS - 1 - are for variables. Symbol number zero is the end-of-input token. - This token is counted in ntokens. The true number of token values - assigned is NTOKENS reduced by one for each alias declaration. - - The rules receive rule numbers 1 to NRULES in the order they are - written. More precisely Bison augments the grammar with the - initial rule, `$accept: START-SYMBOL $end', which is numbered 1, - all the user rules are 2, 3 etc. Each time a rule number is - presented to the user, we subtract 1, so *displayed* rule numbers - are 0, 1, 2... - - Internally, we cannot use the number 0 for a rule because for - instance RITEM stores both symbol (the RHS) and rule numbers: the - symbols are shorts >= 0, and rule number are stored negative. - Therefore 0 cannot be used, since it would be both the rule number - 0, and the token $end). - - Actions are accessed via the rule number. - - The rules themselves are described by several arrays: amongst which - RITEM, and RULES. - - RULES is an array of rules, whose members are: - - RULES[R].lhs -- the symbol of the left hand side of rule R. - - RULES[R].rhs -- the index in RITEM of the beginning of the portion - for rule R. - - RULES[R].prec -- the symbol providing the precedence level of R. - - RULES[R].precsym -- the symbol attached (via %prec) to give its - precedence to R. Of course, if set, it is equal to `prec', but we - need to distinguish one from the other when reducing: a symbol used - in a %prec is not useless. - - RULES[R].assoc -- the associativity of R. - - RULES[R].dprec -- the dynamic precedence level of R (for GLR - parsing). - - RULES[R].merger -- index of merging function for R (for GLR - parsing). - - RULES[R].line -- the line where R was defined. - - RULES[R].useful -- true iff the rule is used (i.e., false if thrown - away by reduce). - - The right hand side is stored as symbol numbers in a portion of - RITEM. - - The length of the portion is one greater than the number of symbols - in the rule's right hand side. The last element in the portion - contains minus R, which identifies it as the end of a portion and - says which rule it is for. - - The portions of RITEM come in order of increasing rule number. - NRITEMS is the total length of RITEM. Each element of RITEM is - called an "item" and its index in RITEM is an item number. - - Item numbers are used in the finite state machine to represent - places that parsing can get to. - - SYMBOLS[I]->prec records the precedence level of each symbol. - - Precedence levels are assigned in increasing order starting with 1 - so that numerically higher precedence values mean tighter binding - as they ought to. Zero as a symbol or rule's precedence means none - is assigned. - - Associativities are recorded similarly in SYMBOLS[I]->assoc. */ - # include "location.h" # include "symtab.h" @@ -145,7 +152,7 @@ return i >= 0; } -/* Rule numbers. */ +/** Rule numbers. */ typedef int rule_number; #define RULE_NUMBER_MAX INT_MAX extern rule_number nrules; @@ -174,24 +181,26 @@ typedef struct { - /* The number of the rule in the source. It is usually the index in - RULES too, except if there are useless rules. */ + /** The number of the rule in the source. It is usually the index in + * RULES too, except if there are useless rules. + */ rule_number user_number; - /* The index in RULES. Usually the rule number in the source, - except if some rules are useless. */ + /** The index in RULES. Usually the rule number in the source, + * except if some rules are useless. + */ rule_number number; symbol *lhs; item_number *rhs; - /* This symbol provides both the associativity, and the precedence. */ + /** This symbol provides both the associativity, and the precedence. */ symbol *prec; int dprec; int merger; - /* This symbol was attached to the rule via %prec. */ + /** This symbol was attached to the rule via %prec. */ symbol *precsym; location location; @@ -203,42 +212,45 @@ extern rule *rules; -/* A function that selects a rule. */ +/** A function that selects a rule. */ typedef bool (*rule_filter) (rule *); -/* Return true IFF the rule has a `number' smaller than NRULES. */ +/** Return true IFF the rule has a `number' smaller than NRULES. */ bool rule_useful_p (rule *r); -/* Return true IFF the rule has a `number' higher than NRULES. */ +/** Return true IFF the rule has a `number' higher than NRULES. */ bool rule_useless_p (rule *r); -/* Return true IFF the rule is not flagged as useful *and* is useful. - In other words, it was discarded because of conflicts. */ +/** Return true IFF the rule is not flagged as useful *and* is useful. + * In other words, it was discarded because of conflicts. + */ bool rule_never_reduced_p (rule *r); -/* Print this rule's number and lhs on OUT. If a PREVIOUS_LHS was - already displayed (by a previous call for another rule), avoid - useless repetitions. */ +/** Print this rule's number and lhs on OUT. If a PREVIOUS_LHS was + * already displayed (by a previous call for another rule), avoid + * useless repetitions. + */ void rule_lhs_print (rule *r, symbol *previous_lhs, FILE *out); -/* Return the length of the RHS. */ +/** Return the length of the RHS. */ int rule_rhs_length (rule *r); -/* Print this rule's RHS on OUT. */ +/** Print this rule's RHS on OUT. */ void rule_rhs_print (rule *r, FILE *out); -/* Print this rule on OUT. */ +/** Print this rule on OUT. */ void rule_print (rule *r, FILE *out); -/* Table of the symbols, indexed by the symbol number. */ +/** Table of the symbols, indexed by the symbol number. */ extern symbol **symbols; -/* TOKEN_TRANSLATION -- a table indexed by a token number as returned - by the user's yylex routine, it yields the internal token number - used by the parser and throughout bison. */ +/** TOKEN_TRANSLATION -- a table indexed by a token number as returned + * by the user's yylex routine, it yields the internal token number + * used by the parser and throughout bison. + */ extern symbol_number *token_translations; extern int max_user_token_number; @@ -247,27 +259,29 @@ /* Dump RITEM for traces. */ void ritem_print (FILE *out); -/* Return the size of the longest rule RHS. */ +/** Return the size of the longest rule RHS. */ size_t ritem_longest_rhs (void); -/* Print the grammar's rules numbers from BEGIN (inclusive) to END - (exclusive) on OUT under TITLE. */ +/** Print the grammar's rules numbers from BEGIN (inclusive) to END + * (exclusive) on OUT under TITLE. + */ void grammar_rules_partial_print (FILE *out, const char *title, rule_filter filter); -/* Print the grammar's rules on OUT. */ +/** Print the grammar's rules on OUT. */ void grammar_rules_print (FILE *out); /* Dump the grammar. */ void grammar_dump (FILE *out, const char *title); -/* Report on STDERR the rules that are not flagged USEFUL, using the - MESSAGE (which can be `useless rule' when invoked after grammar - reduction, or `never reduced' after conflicts were taken into - account). */ +/** Report on STDERR the rules that are not flagged USEFUL, using the + * MESSAGE (which can be `useless rule' when invoked after grammar + * reduction, or `never reduced' after conflicts were taken into + * account). + */ void grammar_rules_never_reduced_report (const char *message); -/* Free the packed grammar. */ +/** Free the packed grammar. */ void grammar_free (void); #endif /* !GRAM_H_ */ Index: location.h =================================================================== RCS file: /sources/bison/bison/src/location.h,v retrieving revision 1.17 diff -u -r1.17 location.h --- location.h 7 Jun 2006 21:17:35 -0000 1.17 +++ location.h 1 Jul 2006 13:26:45 -0000 @@ -18,29 +18,38 @@ the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. */ +/** + * \file location.h + * \brief Defines Location handling for Bison. + */ + #ifndef LOCATION_H_ # define LOCATION_H_ # include "uniqstr.h" -/* A boundary between two characters. */ +/** + * A boundary between two characters. + */ typedef struct { - /* The name of the file that contains the boundary. */ + /** The name of the file that contains the boundary. */ uniqstr file; - /* The (origin-1) line that contains the boundary. - If this is INT_MAX, the line number has overflowed. */ + /** The (origin-1) line that contains the boundary. + * If this is INT_MAX, the line number has overflowed. + */ int line; - /* The (origin-1) column just after the boundary. This is neither a - byte count, nor a character count; it is a column count. - If this is INT_MAX, the column number has overflowed. */ + /** The (origin-1) column just after the boundary. This is neither a + * byte count, nor a character count; it is a column count. + * If this is INT_MAX, the column number has overflowed. + */ int column; } boundary; -/* Set the position of \a a. */ +/** Set the position of \a a. */ static inline void boundary_set (boundary *b, const char *f, int l, int c) { @@ -49,7 +58,7 @@ b->column = c; } -/* Return nonzero if A and B are equal boundaries. */ +/** Return nonzero if A and B are equal boundaries. */ static inline bool equal_boundaries (boundary a, boundary b) { @@ -58,13 +67,13 @@ && UNIQSTR_EQ (a.file, b.file)); } -/* A location, that is, a region of source code. */ +/** A location, that is, a region of source code. */ typedef struct { - /* Boundary just before the location starts. */ + /** Boundary just before the location starts. */ boundary start; - /* Boundary just after the location ends. */ + /** Boundary just after the location ends. */ boundary end; } location; @@ -73,11 +82,12 @@ extern location const empty_location; -/* Set *LOC and adjust scanner cursor to account for token TOKEN of - size SIZE. */ +/** Set *LOC and adjust scanner cursor to account for token TOKEN of + * size SIZE. + */ void location_compute (location *loc, boundary *cur, char const *token, size_t size); void location_print (FILE *out, location loc); -#endif /* ! defined LOCATION_H_ */ +#endif /* defined LOCATION_H_ */ Index: reader.h =================================================================== RCS file: /sources/bison/bison/src/reader.h,v retrieving revision 1.54 diff -u -r1.54 reader.h --- reader.h 26 Jun 2006 04:45:24 -0000 1.54 +++ reader.h 1 Jul 2006 13:26:45 -0000 @@ -20,6 +20,11 @@ the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. */ +/** + * \file reader.h + * \brief Input processing routines. + */ + #ifndef READER_H_ # define READER_H_ @@ -36,19 +41,33 @@ location type_declaration_location; } merger_list; -/* From the parser. */ +/** From the parser. */ extern int gram_debug; int gram_parse (void); char const *token_name (int type); /* From reader.c. */ + +/** Set the start symbol of the grammar */ void grammar_start_symbol_set (symbol *sym, location loc); + +/** Augment the prologue */ void prologue_augment (const char *prologue, location loc, bool post); + +/** Begin a rule */ void grammar_current_rule_begin (symbol *lhs, location loc); + +/** End the current rule */ void grammar_current_rule_end (location loc); + +/** Make a dummy rule for a midrule action */ void grammar_midrule_action (void); + +/** Set the precedence symbol of the current rule */ void grammar_current_rule_prec_set (symbol *precsym, location loc); + +/** Attach dynamic precedence to current rule (for GLR parsers only) */ void grammar_current_rule_dprec_set (int dprec, location loc); void grammar_current_rule_merge_set (uniqstr name, location loc); void grammar_current_rule_symbol_append (symbol *sym, location loc); @@ -58,10 +77,10 @@ extern merger_list *merge_functions; -/* Was %union seen? */ +/** Was %union seen? */ extern bool typed; -/* Should rules have a default precedence? */ +/** Should rules have a default precedence? */ extern bool default_prec; #endif /* !READER_H_ */ Index: symlist.h =================================================================== RCS file: /sources/bison/bison/src/symlist.h,v retrieving revision 1.16 diff -u -r1.16 symlist.h --- symlist.h 26 Jun 2006 04:45:24 -0000 1.16 +++ symlist.h 1 Jul 2006 13:26:45 -0000 @@ -1,6 +1,6 @@ /* Lists of symbols for Bison - Copyright (C) 2002, 2005 Free Software Foundation, Inc. + Copyright (C) 2002, 2005,2006 Free Software Foundation, Inc. This file is part of Bison, the GNU Compiler Compiler. @@ -19,73 +19,83 @@ the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. */ +/** + * \file symlist.h + * \brief Manipulating ::list of symbols. + */ + #ifndef SYMLIST_H_ # define SYMLIST_H_ # include "location.h" # include "symtab.h" -/* A list of symbols, used during the parsing to store the rules. */ + +/** A list of symbols, used during the parsing to store the rules. + */ typedef struct symbol_list { - /* The symbol. */ + /** The symbol. */ symbol *sym; location location; - /* If this symbol is the generated lhs for a midrule but this is the rule in - whose rhs it appears, MIDRULE = a pointer to that midrule. */ + /** If this symbol is the generated lhs for a midrule but this is the rule in + * whose rhs it appears, MIDRULE = a pointer to that midrule. + */ struct symbol_list *midrule; - /* If this symbol is the generated lhs for a midrule and this is that - midrule, MIDRULE_PARENT_RULE = a pointer to the rule in whose rhs it - appears, and MIDRULE_PARENT_RHS_INDEX = its rhs index (1-origin) in the - parent rule. */ + /** If this symbol is the generated lhs for a midrule and this is that + * midrule, MIDRULE_PARENT_RULE = a pointer to the rule in whose rhs it + * appears, and MIDRULE_PARENT_RHS_INDEX = its rhs index (1-origin) in the + * parent rule. + */ struct symbol_list *midrule_parent_rule; int midrule_parent_rhs_index; - /* The action is attached to the LHS of a rule. */ + /** The action is attached to the LHS of a rule. */ const char *action; location action_location; - /* Whether this symbol's value is used in the current action. */ + /** Whether this symbol's value is used in the current action. */ bool used; - /* Precedence/associativity. */ + /** Precedence/associativity. */ symbol *ruleprec; int dprec; int merger; location merger_declaration_location; - /* The list. */ + /** The list. */ struct symbol_list *next; } symbol_list; -/* Create a list containing SYM at LOC. */ +/** Create a list containing SYM at LOC. */ symbol_list *symbol_list_new (symbol *sym, location loc); -/* Print it. */ +/** Print it. */ void symbol_list_print (const symbol_list *l, FILE *f); -/* Prepend SYM at LOC to the LIST. */ +/** Prepend SYM at LOC to the LIST. */ symbol_list *symbol_list_prepend (symbol_list *l, symbol *sym, location loc); -/* Free the LIST, but not the symbols it contains. */ +/** Free the LIST, but not the symbols it contains. */ void symbol_list_free (symbol_list *l); -/* Return its length. */ +/** Return its length. */ unsigned int symbol_list_length (const symbol_list *l); -/* Get symbol N in symbol list L. */ +/** Get symbol N in symbol list L. */ symbol_list *symbol_list_n_get (symbol_list *l, int n); -/* Get the data type (alternative in the union) of the value for - symbol N in rule RULE. */ +/** Get the data type (alternative in the union) of the value for + * symbol N in rule RULE. + */ uniqstr symbol_list_n_type_name_get (symbol_list *l, location loc, int n); -/* The symbol N in symbol list L is USED. */ +/** The symbol N in symbol list L is USED. */ void symbol_list_n_used_set (symbol_list *l, int n, bool used); #endif /* !SYMLIST_H_ */ Index: system.h =================================================================== RCS file: /sources/bison/bison/src/system.h,v retrieving revision 1.77 diff -u -r1.77 system.h --- system.h 6 Jun 2006 16:40:06 -0000 1.77 +++ system.h 1 Jul 2006 13:26:45 -0000 @@ -20,10 +20,12 @@ #ifndef BISON_SYSTEM_H #define BISON_SYSTEM_H -/* flex 2.5.31 gratutiously defines macros like INT8_MIN. But this - runs afoul of pre-C99 compilers that have or - , which are included below if available. It also runs - afoul of pre-C99 compilers that define these macros in . */ +/** + * flex 2.5.31 gratutiously defines macros like INT8_MIN. But this + * runs afoul of pre-C99 compilers that have or + * , which are included below if available. It also runs + * afoul of pre-C99 compilers that define these macros in . + */ #if ! defined __STDC_VERSION__ || __STDC_VERSION__ < 199901 # undef INT8_MIN # undef INT16_MIN @@ -59,8 +61,10 @@ #endif #if ! HAVE_UINTPTR_T -/* This isn't perfect, but it's good enough for Bison, which needs - only to hash pointers. */ +/* + * This isn't perfect, but it's good enough for Bison, which needs + * only to hash pointers. + */ typedef size_t uintptr_t; #endif