* inflow.c (child_terminal_inferior): Add comment.

	(child_terminal_ours_for_output): Add comment.
	(child_terminal_ours): Add comment.
	* linux-nat.c (linux_nat_terminal_inferior): Add comment.
	(linux_nat_terminal_ours): Add comment.

3 files changed, 33 insertions, 5 deletions

diff --git a/gdb/ChangeLog b/gdb/ChangeLog
index 572cd44..e494a2a 100644
--- a/gdb/ChangeLog
+++ b/gdb/ChangeLog
@@ -1,3 +1,11 @@
+2014-07-31  Doug Evans  <dje@google.com>
+
+	* inflow.c (child_terminal_inferior): Add comment.
+	(child_terminal_ours_for_output): Add comment.
+	(child_terminal_ours): Add comment.
+	* linux-nat.c (linux_nat_terminal_inferior): Add comment.
+	(linux_nat_terminal_ours): Add comment.
+
 2014-07-31  Gary Benson  <gbenson@redhat.com>
 
 	* common/btrace-common.h: Do not include defs.h or server.h.
diff --git a/gdb/inflow.c b/gdb/inflow.c
index 5f81de2..f13efea 100644
--- a/gdb/inflow.c
+++ b/gdb/inflow.c
@@ -267,7 +267,11 @@ child_terminal_init (struct target_ops *self)
 }
 
 /* Put the inferior's terminal settings into effect.
-   This is preparation for starting or resuming the inferior.  */
+   This is preparation for starting or resuming the inferior.
+
+   N.B. Targets that want to use this with async support must build that
+   support on top of this (e.g., the caller still needs to remove stdin
+   from the event loop).  E.g., see linux_nat_terminal_inferior.  */
 
 void
 child_terminal_inferior (struct target_ops *self)
@@ -348,7 +352,10 @@ child_terminal_inferior (struct target_ops *self)
    so that no input is discarded.
 
    After doing this, either terminal_ours or terminal_inferior
-   should be called to get back to a normal state of affairs.  */
+   should be called to get back to a normal state of affairs.
+
+   N.B. The implementation is (currently) no different than
+   child_terminal_ours.  See child_terminal_ours_1.  */
 
 void
 child_terminal_ours_for_output (struct target_ops *self)
@@ -358,7 +365,11 @@ child_terminal_ours_for_output (struct target_ops *self)
 
 /* Put our terminal settings into effect.
    First record the inferior's terminal settings
-   so they can be restored properly later.  */
+   so they can be restored properly later.
+
+   N.B. Targets that want to use this with async support must build that
+   support on top of this (e.g., the caller still needs to add stdin to the
+   event loop).  E.g., see linux_nat_terminal_ours.  */
 
 void
 child_terminal_ours (struct target_ops *self)
diff --git a/gdb/linux-nat.c b/gdb/linux-nat.c
index 8d4251f..5a791bc 100644
--- a/gdb/linux-nat.c
+++ b/gdb/linux-nat.c
@@ -4595,7 +4595,9 @@ linux_nat_supports_disable_randomization (struct target_ops *self)
 
 static int async_terminal_is_ours = 1;
 
-/* target_terminal_inferior implementation.  */
+/* target_terminal_inferior implementation.
+
+   This is a wrapper around child_terminal_inferior to add async support.  */
 
 static void
 linux_nat_terminal_inferior (struct target_ops *self)
@@ -4618,7 +4620,14 @@ linux_nat_terminal_inferior (struct target_ops *self)
   set_sigint_trap ();
 }
 
-/* target_terminal_ours implementation.  */
+/* target_terminal_ours implementation.
+
+   This is a wrapper around child_terminal_ours to add async support (and
+   implement the target_terminal_ours vs target_terminal_ours_for_output
+   distinction).  child_terminal_ours is currently no different than
+   child_terminal_ours_for_output.
+   We leave target_terminal_ours_for_output alone, leaving it to
+   child_terminal_ours_for_output.  */
 
 static void
 linux_nat_terminal_ours (struct target_ops *self)