Re: [PATCH] Add comments to terminal_ours/inferior functions

[Doug Evans <dje at google dot com>]

Pedro Alves writes:
 > On 07/30/2014 07:26 PM, Doug Evans wrote:
 > 
 > > 
 > > 2014-07-30  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.
 > > 
 > 
 > Looks good.
 > 
 > Thanks,
 > Pedro Alves
 > 

There was a cut-n-paste error in the comment for child_terminal_inferior.
Here is what I checked in.
Thanks.

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.

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)