add warning of subtle gotcha that can happen with mutable data buffers

darcs-hash:38f6cc8860a66686cffaa2f4ac3fe56ec1da7c41

diff --git a/pyfec/fec/fecmodule.c b/pyfec/fec/fecmodule.c
index 7758ee71b869eb245fd93fc7846f3294fdac2a2b..211079c25ed56c3ac264d02a1168fb346fec51ae 100644 (file)
--- a/pyfec/fec/fecmodule.c
+++ b/pyfec/fec/fecmodule.c
@@ -86,7 +86,7 @@ static char Encoder_encode__doc__[] = "\
 Encode data into m packets.\
 @param inshares: a sequence of k buffers of data to encode -- these are the k primary shares, i.e. the input data split into k pieces (for best performance, make it a tuple instead of a list)\n\
 @param desired_shares_nums optional sorted sequence of sharenums indicating which shares to produce and return;  If None, all m shares will be returned (in order).  (For best performance, make it a tuple instead of a list.)\n\
-@returns: a list of buffers containing the requested shares\n\
+@returns: a list of buffers containing the requested shares; Note that if any of the input shares were 'primary shares', i.e. their shareid was < k, then the result sequence will contain a Python reference to the same Python object as was passed in.  As long as the Python object in question is immutable (i.e. a string) then you don't have to think about this detail, but if it is mutable (i.e. an array), then you have to be aware that if you subsequently mutate the contents of that object then that will also change the contents of the sequence that was returned from this call to encode().\n\
 ";
 
 static PyObject *