Re: encapsulating code properties

[Joel E. Denny]

On Mon, 13 Nov 2006, Joel E. Denny wrote:

> +2006-11-13  Joel E. Denny  <address@hidden>
> +
> +     Encapsulate code properties and related functionality for the various
> +     destructors, printers, and actions into a code_props structure and
> +     interface.

> Index: src/scan-code.h
> ===================================================================
> RCS file: /sources/bison/bison/src/scan-code.h,v
> retrieving revision 1.6
> diff -p -u -r1.6 scan-code.h
> --- src/scan-code.h   12 Nov 2006 07:39:37 -0000      1.6
> +++ src/scan-code.h   14 Nov 2006 02:36:57 -0000

> +/**
> + * \pre
> + *   - <tt>self != NULL</tt>.
> + *   - <tt>code != NULL</tt>.
> + *   - <tt>rule != NULL</tt>.
> + *   - \c code is the untranslated action of the rule for which \c rule is 
> the
> + *     LHS node.  Thus, \c code possibly contains Bison escapes such as $$, 
> $1,
> + *     $2, etc referring to the values of the rule.
> + * \post
> + *   - \c self has been overwritten to represent the specified rule action.
> + *   - \c self does not claim responsibility for the memory of \c code or
> + *     \c rule.
> + */
> +void code_props_rule_action_init (code_props *self, char const *code,
> +                                  location code_loc, struct symbol_list 
> *rule);

I normally consider it redundant to document the transfer of memory 
responsibility (or rather the lack of it) in the case of a const pointer.  
For example, in the last postcondition above, I see no reason to mention 
code, but I think mentioning rule is worthwhile.  There are several other 
places in this file where I botched this as well, so I'll need to fix it 
if the patch is otherwise accepted.