[COMMITTED] Clean up examples for -Wdangling-pointer [PR109708]

[Sandra Loosemore <sandra@codesourcery.com>]

gcc/ChangeLog
	PR c/109708
	* doc/invoke.texi (Warning Options): Fix broken example and
	clean up/reorganize the others.  Also describe what the short-form
	options mean.
---
 gcc/doc/invoke.texi | 56 +++++++++++++++++++++++++++------------------
 1 file changed, 34 insertions(+), 22 deletions(-)

diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 930c5dc7236..f7a6e11d20e 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -9423,51 +9423,63 @@ levels but may yield different results with optimization than without.
 
 @table @gcctabopt
 @item -Wdangling-pointer=1
-At level 1 the warning diagnoses only unconditional uses of dangling pointers.
-For example
+At level 1, the warning diagnoses only unconditional uses of dangling pointers.
+
+@item -Wdangling-pointer=2
+At level 2, in addition to unconditional uses the warning also diagnoses
+conditional uses of dangling pointers.
+@end table
+
+The short form @option{-Wdangling-pointer} is equivalent to
+@option{-Wdangling-pointer=2}, while @option{-Wno-dangling-pointer} and
+@option{-Wdangling-pointer=0} have the same effect of disabling the warnings.
+@option{-Wdangling-pointer=2} is included in @option{-Wall}.
+
+This example triggers the warning at level 1; the address of the unnamed
+temporary is unconditionally referenced outside of its scope.
+
 @smallexample
-int f (int c1, int c2, x)
+char f (char c1, char c2, char c3)
 @{
-  char *p = strchr ((char[])@{ c1, c2 @}, c3);
-  // warning: dangling pointer to a compound literal
-  return p ? *p : 'x';
+  char *p;
+  @{
+    p = (char[]) @{ c1, c2, c3 @};
+  @}
+  // warning: using dangling pointer 'p' to an unnamed temporary
+  return *p;
 @}
 @end smallexample
+
 In the following function the store of the address of the local variable
-@code{x} in the escaped pointer @code{*p} also triggers the warning.
+@code{x} in the escaped pointer @code{*p} triggers the warning at
+level 1.
+
 @smallexample
 void g (int **p)
 @{
   int x = 7;
-  // warning: storing the address of a local variable in *p
+  // warning: storing the address of local variable 'x' in '*p'
   *p = &x;
 @}
 @end smallexample
 
-@item -Wdangling-pointer=2
-At level 2, in addition to unconditional uses the warning also diagnoses
-conditional uses of dangling pointers.
-
-For example, because the array @var{a} in the following function is out of
-scope when the pointer @var{s} that was set to point is used, the warning
-triggers at this level.
+In this example, the array @var{a} is out of
+scope when the pointer @var{s} is used.  Since the code that sets @code{s}
+is conditional, the warning triggers at level 2.
 
 @smallexample
-void f (char *s)
+extern void frob (const char *);
+void h (char *s)
 @{
   if (!s)
     @{
       char a[12] = "tmpname";
       s = a;
     @}
-  // warning: dangling pointer to a may be used
-  strcat (s, ".tmp");
-  ...
+  // warning: dangling pointer 's' to 'a' may be used
+  frob (s);
 @}
 @end smallexample
-@end table
-
-@option{-Wdangling-pointer=2} is included in @option{-Wall}.
 
 @opindex Wdate-time
 @opindex Wno-date-time
-- 
2.31.1