Document setter for mutable attributes (#6198)

In particular, add an example that shows the differences.
(I do not like it at all that setters of mutable attributes
replace stored values,
but I think it is too late to change this behaviour.)

Author: ThomasBreuer

doc/ref/types.xml

@@ -533,6 +533,34 @@ for example, <C>Setter( Size )( <A>obj</A>, <A>val</A> )</C>
 sets <A>val</A> as size of the
 object <A>obj</A> if the size was not yet known.
 <P/>
+Calling the setter an of attribute for an object which stores already
+a value for this attribute <E>has no effect</E>,
+except if the attribute has been created as a <E>mutable</E> attribute
+(see <Ref Func="NewAttribute"/>).
+For mutable attributes, each call of the setter
+<E>replaces the stored value</E>.
+(Usually mutable attributes are used to store a mutable list or record once,
+and later add data to this value, and then one should take care not to call
+the setter of the attribute again.)
+<P/>
+<Example><![CDATA[
+gap> imm_attr:= NewAttribute( "imm_attr", IsGroup );;
+gap> mut_attr:= NewAttribute( "mut_attr", IsGroup, "mutable" );;
+gap> G:= SymmetricGroup( 4 );;
+gap> Setter( imm_attr )( G, 0 );
+gap> imm_attr( G );
+0
+gap> Setter( imm_attr )( G, 1 );  # This call has no effect.
+gap> imm_attr( G );
+0
+gap> Setter( mut_attr )( G, 0 );
+gap> mut_attr( G );
+0
+gap> Setter( mut_attr )( G, 1 );  # This call replaces the stored value.
+gap> mut_attr( G );
+1
+]]></Example>
+<P/>
 For each attribute <A>attr</A> that is declared with
 <Ref Func="DeclareAttribute"/> resp.&nbsp;<Ref Func="DeclareProperty"/>,
 tester and setter are automatically made accessible by the names

lib/oper.g

@@ -1272,9 +1272,10 @@ end );
 ##  <Ref Oper="SylowSubgroup"/>,
 ##  and this list is mutable because one may want to enter groups into it
 ##  as they are computed.
-##  <!-- in the current implementation, one can overwrite values of mutable-->
-##  <!-- attributes; is this really intended?-->
-##  <!-- if yes then it should be documented!-->
+##  <P/>
+##  Mutable and immutable attributes behave differently w. r. t. repeated
+##  calls of the function that sets the attribute value,
+##  see <Ref Func="Setter"/>.
 ##  <P/>
 ##  If no argument for <A>rank</A> is given, then the rank of the tester is 1.
 ##  <P/>