diff --git a/doc/shell.dox b/doc/shell.dox
index 2cf400a5..f51c489c 100644
--- a/doc/shell.dox
+++ b/doc/shell.dox
@@ -69,6 +69,9 @@ If you want define its dimensions (number of rows and columns),
 call ssh_channel_request_pty_size() instead. It's also possible to change
 the dimensions after creating the pty with ssh_channel_change_pty_size().
 
+These two functions configure the pty using the same terminal modes that
+stdin has. If stdin isn't a TTY, they use default modes that configure
+the pty with in canonical mode and e.g. preserving CR and LF characters.
 If you want to change the terminal modes used by the pty (e.g. to change
 CRLF handling), use ssh_channel_request_pty_size_modes(). This function
 accepts an additional "modes" buffer that is expected to contain encoded