Nine files document a saturation to 1.31 format that the code does not perform

[DanielMBouyou]

Hi,
Following #327, here are the other files carrying the same wording, as you asked.

Ten files document the 2.62 accumulator being "truncated to 1.32 format and then
saturated to 1.31 format" at origin/main (c0c8640). Nine of them need the same
change as #327. The tenth is correct and is listed for completeness.

File	Function	Doc line	Scalar path
FilteringFunctions/arm_conv_q31.c	arm_conv_q31	59	no clamp, 8 bare narrowing sites
FilteringFunctions/arm_correlate_q31.c	arm_correlate_q31	59	no clamp, 9 sites
FilteringFunctions/arm_fir_decimate_q31.c	arm_fir_decimate_q31	55	no clamp, 5 sites
FilteringFunctions/arm_fir_interpolate_q31.c	arm_fir_interpolate_q31	56	no clamp, 6 sites
FilteringFunctions/arm_fir_q31.c	arm_fir_q31	56	no clamp, 4 sites
FilteringFunctions/arm_lms_norm_q31.c	arm_lms_norm_q31	59-60	no clamp, 1 site
FilteringFunctions/arm_lms_q31.c	arm_lms_q31	60-61	no clamp, 1 site
MatrixFunctions/arm_mat_mult_q31.c	arm_mat_mult_q31	60	no clamp, :786
MatrixFunctions/arm_mat_mult_opt_q31.c	arm_mat_mult_opt_q31	61	no clamp, :757
MatrixFunctions/arm_mat_cmplx_mult_q31.c	arm_mat_cmplx_mult_q31	60	clamps, clip_q63_to_q31 at :1107-1108

arm_mat_cmplx_mult_q31 is the exception: its scalar path really does saturate,
so its documentation is accurate and I would leave it alone.

What I did not check, so you know where the gaps are:

• I only classified the scalar paths. The MVEI and NEON kernels narrow through
  vector intrinsics rather than a (q31_t) cast, so my search does not see them
  and I make no claim about them. In Overflow Handling in arm_fir_q31 Function #175 you wrote that Helium saturates.
• arm_mat_mult_q31.c:375 and arm_mat_mult_opt_q31.c:380 contain bare casts
  inside the ARM_MATH_MVEI branch. I did not establish whether they are reached
  on a Helium build.
• Nothing was compiled or executed. This is a source reading only.
• The same wording appears in 12 q15 files ("1.15 format") and 5 q7 files
  ("1.7 format"). I have not examined those, so I say nothing about them, but
  the scope may be wider than these ten.

Happy to send the nine doc edits as a PR if that is easier than doing them
yourself. Otherwise this list is all you asked for.

[christophe0606]

@DanielMBouyou I'll be off for some time so this issue will be pending until I am back. But it won't be forgotten.

[DanielMBouyou]

Ok no problem and thanks @christophe0606

Correction to my own wording above: the sentence I quoted appears in 2 of the 10
files, not in all of them. The clause takes four forms:

Wording	Files
"right shifted by 31 bits and saturated..."	arm_conv_q31, arm_correlate_q31, arm_mat_mult_q31, arm_mat_mult_opt_q31, arm_mat_cmplx_mult_q31
"truncated to 1.32 format and then saturated..."	arm_fir_decimate_q31, arm_fir_interpolate_q31
"After all multiply-accumulates..., right shifted by 31 bits..."	arm_fir_q31
"...is shifted and saturated..."	arm_lms_norm_q31, arm_lms_q31

The file list, the line numbers and the verdicts in the table above are unchanged.