ObjC doc patch

[Nicola Pero <nicola at brainstorm dot co dot uk>]

This patch extends and updates the ObjC documentation (including the new
changes).

Ok to apply ?

Wed Aug 28 10:03:52 2002  Nicola Pero  <n.pero@mi.flashnet.it>

        * doc/cpp.texi (__NEXT_RUNTIME__): Extended documentation.
        * doc/invoke.texi (-fnext-runtime, -Wno-protocol, -Wselector):
        Extended, updated documentation.
        (-Wundeclared-selector): Documented.

Index: cpp.texi
===================================================================
RCS file: /cvs/gcc/gcc/gcc/doc/cpp.texi,v
retrieving revision 1.44
diff -u -r1.44 cpp.texi
--- cpp.texi    27 Aug 2002 10:53:06 -0000      1.44
+++ cpp.texi    28 Aug 2002 09:26:47 -0000
@@ -2008,8 +2008,10 @@
 handling.
 
 @item __NEXT_RUNTIME__
-This macro is defined, with value 1, when the NeXT runtime
-(as in @option{-fnext-runtime}) is in use for Objective-C.
+This macro is defined, with value 1, if (and only if) the NeXT runtime
+(as in @option{-fnext-runtime}) is in use for Objective-C.  If the GNU
+runtime is used, this macro is not defined, so that you can use this
+macro to determine which runtime (NeXT or GNU) is being used.
 
 @item __TARGET_BITS_ORDER__
 This macro describes the target's bits order in a byte.  Its value is
Index: invoke.texi
===================================================================
RCS file: /cvs/gcc/gcc/gcc/doc/invoke.texi,v
retrieving revision 1.177
diff -u -r1.177 invoke.texi
--- invoke.texi 27 Aug 2002 22:14:48 -0000      1.177
+++ invoke.texi 28 Aug 2002 09:26:59 -0000
@@ -199,7 +199,7 @@
 @gccoptlist{
 -fconstant-string-class=@var{class-name} @gol
 -fgnu-runtime  -fnext-runtime  -gen-decls @gol
--Wno-protocol  -Wselector}
+-Wno-protocol  -Wselector -Wundeclared-selector}
 
 @item Language Independent Options
 @xref{Language Independent Options,,Options to Control Diagnostic
Messages Formatting}.
@@ -1730,7 +1730,9 @@
 @item -fnext-runtime
 @opindex fnext-runtime
 Generate output compatible with the NeXT runtime.  This is the default
-for NeXT-based systems, including Darwin and Mac OS X@.
+for NeXT-based systems, including Darwin and Mac OS X@.  The macro
+@code{__NEXT_RUNTIME__} is predefined if (and only if) this option is
+used.
 
 @item -gen-decls
 @opindex gen-decls
@@ -1739,12 +1741,39 @@
 
 @item -Wno-protocol
 @opindex Wno-protocol
-Do not warn if methods required by a protocol are not implemented
-in the class adopting it.
+If a class is declared to implement a protocol, a warning is issued for
+every method in the protocol that is not implemented by the class.  The
+default behaviour is to issue a warning for every method not explicitly
+implemented in the class, even if a method implementation is inherited
+from the superclass.  If you use the @code{-Wno-protocol} option, then
+methods inherited from the superclass are considered to be implemented,
+and no warning is issued for them.
 
 @item -Wselector
 @opindex Wselector
-Warn if a selector has multiple methods of different types defined.
+Warn if multiple methods of different types for the same selector are
+found during compilation.  The check is performed on the list of methods
+in the final stage of compilation.  Additionally, a check is performed
+that for each selector appearing in a @code{@@selector(@dots{})}
+expression, a corresponding method with that selector has been found
+during compilation.  Because these checks scan the method table only at
+the end of compilation, these warnings are not produced if the final
+stage of compilation is not reached, for example because an error is
+found during compilation, or because the @code{-fsyntax-only} option is
+being used.
+
+@item -Wundeclared-selector
+@opindex Wundeclard-selector
+Warn if a @code{@@selector(@dots{})} expression referring to an
+undeclared selector is found.  A selector is considered undeclared if no
+method with that name has been declared (explicitly, in an
+@code{@@interface} or @code{@@protocol} declaration, or implicitly, in
+an @code{@@implementation} section) before the
+@code{@@selector(@dots{})} expression.  This option always performs its
+checks as soon as a @code{@@selector(@dots{})} expression is found
+(while @code{-Wselector} only performs its checks in the final stage of
+compilation), and so additionally enforces the coding style convention
+that methods and selectors must be declared before being used.
 
 @c not documented because only avail via -Wp
 @c @item -print-objc-runtime-info