documentation: documented functions from userinput.h

src/userinput.h

@@ -1,13 +1,79 @@
 #ifndef USERINPUT_H
 #define USERINPUT_H
+
+/// userinput.h provides functions for retrieving user input.
+/// The functions are named get + placeholder used by printf for the given datatype.
+/// string -> gets
+/// short ind -> gethd
+/// int -> getd
+/// long -> getld
+/// long long -> getlld
+/// unsigned short -> gethu
+/// unsigned int -> getu
+/// unsigned long -> getlu
+/// unsigned long long -> getllu
+/// double -> getlf
+/// The provided functions handle validating the user input and ask again for input 
+/// with the given message until it is valid.
+
+/// Using the given message gets asks the user to enter a string repeatedly
+/// until its length is between minLength and maxLength (both inclusive).  
+/// The obtained string is then returned.
+/// If you don't want to enforce a minLength or a maxLength you can assign it to NULL.  
 char *gets(char *message, unsigned long *minLength, unsigned long *maxLength);
+
+/// Using the given message gethd asks the user to enter a short repeatedly
+/// until it is in the valid range for a short and between min and max (both inclusive) if provided.
+/// The obtained short is then returned.
+/// If you don't want to enforce a min or max you can assign it to NULL.
 short gethd(char *message, short *min, short *max);
+
+/// Using the given message getd asks the user to enter an int repeatedly
+/// until it is in the valid range for an int and between min and max (both inclusive) if provided.
+/// The obtained int is then returned.
+/// If you don't want to enforce a min or max you can assign it to NULL.
 int getd(char *message, int *min, int *max);
+
+/// Using the given message getld asks the user to enter a long repeatedly
+/// until it is in the valid range for a long and between min and max (both inclusive) if provided.
+/// The obtained long is then returned.
+/// If you don't want to enforce a min or max you can assign it to NULL.
 long getld(char *message, long *min, long *max);
+
+/// Using the given message getlld asks the user to enter a long long repeatedly
+/// until it is in the valid range for a long long and between min and max (both inclusive) if provided.
+/// The obtained long is then returned.
+/// If you don't want to enforce a min or max you can assign it to NULL.
 long long getlld(char *message, long long *min, long long *max);
+
+/// Using the given message gethu asks the user to enter an unsigned short repeatedly
+/// until it is in the valid range for an unsigned short and between min and max (both inclusive) if provided.
+/// The obtained unsigned short is then returned.
+/// If you don't want to enforce a min or max you can assign it to NULL.
 unsigned short gethu(char *message, unsigned short *min, unsigned short *max);
+
+/// Using the given message getu asks the user to enter an unsigned int repeatedly
+/// until it is in the valid range for an unsigned int and between min and max (both inclusive) if provided.
+/// The obtained unsigned int is then returned.
+/// If you don't want to enforce a min or max you can assign it to NULL.
 unsigned int getu(char *message, unsigned int *min, unsigned int *max);
+
+/// Using the given message getlu asks the user to enter an unsigned long repeatedly
+/// until it is in the valid range for an unsigned long and between min and max (both inclusive) if provided.
+/// The obtained unsigned long is then returned.
+/// If you don't want to enforce a min or max you can assign it to NULL.
 unsigned long getlu(char *message, unsigned long *min, unsigned long *max);
+
+/// Using the given message getllu asks the user to enter an unsigned long long repeatedly
+/// until it is in the valid range for an unsigned long long and between min and max (both inclusive) if provided.
+/// The obtained unsigned long long is then returned.
+/// If you don't want to enforce a min or max you can assign it to NULL.
 unsigned long long getllu(char *message, unsigned long long *min, unsigned long long *max);
+
+/// Using the given message getlf asks the user to enter a double repeatedly
+/// until it is in the valid range for a double, between min and max (both inclusive),
+/// greater than the given greaterThan and smaller than the given smallerThan.
+/// The obtained double is then returned.
+/// If you don't want to enforce a min, max, greaterThan or smallerThan you can assign them to NULL.
 double getlf(char *message, double *min, double *max, double *greaterThan, double *smallerThan);
 #endif