Revising to align with stdio fgets

include/conio.h

@@ -110,22 +110,18 @@ char cgetc (void);
 ** 1 (see below), a blinking cursor is displayed while waiting.
 */
 
-char *cgets (char *buffer);
-/* Get a string of characters directly from the console. The standard interface
-** is quirky:
+char* __fastcall__ cgets (char *buffer, int size);
+/* Get a string of characters directly from the console. The function returns
+** when size - 1 characters or either CR/LF are read. Note the parameters are
+** more aligned with stdio fgets() as opposed to the quirky "standard" conio
+** cgets(). Besides providing saner parameters, the function also echoes CRLF
+** when either CR/LF are read but does NOT append either in the buffer. This is
+** to correspond to stdio fgets() which echoes CRLF, but prevents a "gotcha"
+** where the buffer might not be able to accommodate both CR and LF at the end.
 **
-**   - set buffer[0] to the size of the buffer - 2, must be > 0
-**   - call cgets
-**   - buffer[1] will have the number of characters read
-**   - the actual string starts at buffer + 2
-**   - terminating \0 is appended
-**   - therefore the maximum number of characters which can be read is the size
-**     of the buffer - 3!
-**   - note: CR/LF are NOT echoed, typically a following call to cputs or
-**     cprintf will need "\r\n" prepended - "standard" behavior
-**
-**   param: buffer - where to save the input
-**  return: buffer + 2 (i.e. start of the string) if successful, NULL otherwise
+**   param: buffer - where to save the input, must be non-NULL
+**   param: size - size of the buffer, must be > 1
+**  return: buffer if successful, NULL on error
 **  author: Russell-S-Harper
 */