docs: homogenize doxygen across cores, libraries, system and variants

Review doxygen comments in headers and sources under cores/, libraries/,
system/STM32* and variants/ (excluding cores/arduino/api, system/Drivers
and system/Middlewares) and apply one style:

- API contracts (@brief, @PARAM, @return, @note) live in headers. Functions
  declared in a header are documented there and their duplicate blocks are
  removed from the source file.
- Static and source-only functions are documented directly above their
  definition in the .c/.cpp file.
- Parameter names in header declarations now match their definitions in
  HardwareTimer.h, analog.h, Wire.h, VirtIO mbox_ipcc.h, Serial.h and
  stm32_def.h. This is a name-only change with no ABI impact.
- @PARAM None is removed, since it documents no parameter. @RetVal None is
  removed from cores/ and libraries/ and kept only in ST-derived
  system/STM32* files.
- Undocumented functions are documented, including HardwareTimer methods,
  Wire and twi helpers, SPI, EEPROM, Servo, USBDevice, Serial Uart, WSerial
  serialEvent hooks, pins_arduino, variant clock helpers, and assert_failed in
  the hal_conf_default headers.
- Struct and class member docs are added in cdc_queue.h, EEPROM.h (EERef and
  EEPtr index) and pinmap.h (PinMap and NP).
- usbd_cdc.h \defgroup entries get titles. The @file and \file names in
  syscalls.c and interrupt.cpp are corrected. The unnamed size parameter of
  operator delete in new.cpp is no longer documented with @PARAM.

Doxygen (1.9.8) run over the same scope, excluding cores/arduino/api and the
Drivers and Middlewares folders: "(function) ... is not documented" warnings
drop from 210 to 7. Five of the remaining seven are __attribute__ misparses
(aligned/used). The other two are not missing docs: HAL_FLASH_Lock is a call
site in stm32_eeprom.c whose prototype lives in the excluded ST HAL headers,
and stm32_interrupt_enable is documented in interrupt.h, but Doxygen cannot
see that prototype under its __cplusplus guard. In USBDevice, the #ifdef
blocks in usbd_cdc.h and usbd_hid_composite.h are reordered with equivalent
declarations. Apart from the parameter-name fixes and that reordering, only
comments changed.

Signed-off-by: Frederic Pillon <frederic.pillon@st.com>
Assisted-by: GitHub Copilot: Claude Haiku 5.5
Assisted-by: GitHub Copilot: Claude Sonnet 5.5
Signed-off-by: Frederic Pillon <frederic.pillon@st.com>

Author: fpistm

CI/update/templates/generic_clock.c

@@ -15,9 +15,7 @@
 #include "pins_arduino.h"
 
 /**
-  * @brief  System Clock Configuration
-  * @param  None
-  * @retval None
+  * @brief System Clock Configuration
   */
 WEAK void SystemClock_Config(void)
 {

cores/arduino/Arduino.h

@@ -17,10 +17,18 @@
   Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 */
 
+/**
+ * @file Arduino.h
+ * @brief Main include file of the Arduino core for STM32.
+ *
+ * Includes the Arduino API, the wiring extensions and the pins of the selected variant.
+ */
+
 #ifndef Arduino_h
 #define Arduino_h
 
 #ifndef GCC_VERSION
+/** GCC version encoded as major * 10000 + minor * 100 + patch level. */
 #define GCC_VERSION (__GNUC__ * 10000 \
                      + __GNUC_MINOR__ * 100 \
                      + __GNUC_PATCHLEVEL__)

cores/arduino/Serial.cpp

@@ -22,6 +22,11 @@
   Modified 3 December 2013 by Matthijs Kooijman
 */
 
+/**
+ * @file Serial.cpp
+ * @brief Hardware serial (Uart class) implementation and SerialN / SerialLPN instances.
+ */
+
 #include <stdio.h>
 #include "Arduino.h"
 #include "Serial.h"