-/* Appends to ST a newline-terminated line read from STREAM, but
- no more than MAX_LENGTH characters.
- Newline is the last character of ST on return, if encountering
- a newline was the reason for terminating.
- Returns true if at least one character was read from STREAM
- and appended to ST, false if no characters at all were read
- before an I/O error or end of file was encountered (or
- MAX_LENGTH was 0). */
+/* Reads characters from STREAM and appends them to ST, stopping
+ after MAX_LENGTH characters, after appending a newline, or
+ after an I/O error or end of file was encountered, whichever
+ comes first. Returns true if at least one character was added
+ to ST, false if no characters were read before an I/O error or
+ end of file (or if MAX_LENGTH was 0).
+
+ This function accepts LF, CR LF, and CR sequences as new-line,
+ and translates each of them to a single '\n' new-line
+ character in ST. */