Analogin: add defined behavior

hal/analogin_api.h

@@ -35,9 +35,29 @@ typedef struct analogin_s analogin_t;
 
 /**
  * \defgroup hal_analogin Analogin hal functions
+ *
+ * # Defined behaviour
+ * * The function ::analogin_init initializes the analogin peripheral
+ * * The function ::analogin_read reads the input voltage, represented as a float in the range [0.0, 1.0]
+ * * The function ::analogin_read_u16 reads the value from analogin pin, represented as an unsigned 16bit value
+ *
+ * # Undefined behaviour
+ *
+ * * ::analogin_init is called with invalid pin (which does not support analog input function)
+ * * Calling ::analogin_read, ::analogin_read_u16 before ::analogin_init
  * @{
  */
 
+/**
+ * \defgroup hal_analogin_tests Analogin hal tests
+ * The Analogin HAL tests ensure driver conformance to defined behaviour.
+ *
+ * To run the Analogin hal tests use the command:
+ *
+ *     mbed test -t <toolchain> -m <target> -n tests-mbed_hal_fpga_ci_test_shield-analogin
+ *
+ */
+
 /** Initialize the analogin peripheral
  *
  * Configures the pin used by analogin.