Variable naming in bitset changeset

[Rik]

5/16/12

Jordi,

When you re-wrote bitset the function definition was changed as shown below:

-function C = bitset (A, n, val)
+function A = bitset (A, n, val)

However, the documentation is still written as

@deftypefnx {Function File} address@hidden =} bitset (@var{A}, @var{n}, 
@var{val})

In the interests of clarity, I have worked throughout Octave to make the
documentation match the code and vice versa.  The interpreter doesn't care
what the variable names are, but often the only clues to what a variable
does are in the documentation string and that connection becomes harder
when I have to maintain a lookup table in my head between documented
variable and function variable.  It use to be a lot worse with things like
'y = f (x)' in the documentation and 'function retval = f (A)' in the code.

If there was a performance reason for making the change then that might
trump my code clarity concerns.  Otherwise, I would like to change the
naming back to C.  In particular, I have a hazy memory of an incident where
we had the same variable name for both input and output and it became very
difficult to tell whether a line of code was referring to the input or the
output. 

Incidentally, the naming convention for the bitXXX functions was derived
from Matlab (http://www.mathworks.com/help/techdoc/ref/bitset.html).  The
reason for C as an output is that there are several bit functions which
take two arguments (bitand, bitor, ...) and once the first argument is A,
the second might as well be B, and that leaves C as the output (C = A +
B).  For the single argument bitfunctions one then has C = f (A) just to
keep up the convention.

Cheers,
Rik