[RFA]: ObjC Documentation

[RFA]: ObjC Documentation

[Adam Fedor]

[-- Attachment #1: Type: text/plain, Size: 0 bytes --]



[-- Attachment #2: objc-docs.patch --]
[-- Type: text/plain, Size: 5444 bytes --]

2003-04-29  Adam Fedor  <fedor@gnu.org>

	* gdb.texinfo: Add Objective-C documentation.

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.156
diff -u -p -r1.156 gdb.texinfo
--- gdb.texinfo	14 Apr 2003 18:42:28 -0000	1.156
+++ gdb.texinfo	30 Apr 2003 03:30:48 -0000
@@ -210,6 +210,10 @@ syntax.
 it may be necessary to refer to some variables with a trailing
 underscore.
 
+@cindex Objective-C
+@value{GDBN} can be used to debug programs written in Objective-C,
+using either the Apple/NeXT or the GNU Objective-C runtime.
+
 @menu
 * Free Software::               Freely redistributable software
 * Contributors::                Contributors to GDB
@@ -3180,7 +3184,8 @@ end
 @cindex overloading
 @cindex symbol overloading
 
-Some programming languages (notably C@t{++}) permit a single function name
+Some programming languages (notably C@t{++} and Objective-C) permit a 
+single function name
 to be defined several times, for application in different contexts.
 This is called @dfn{overloading}.  When a function name is overloaded,
 @samp{break @var{function}} is not enough to tell @value{GDBN} where you want
@@ -7499,6 +7504,9 @@ C source file
 @itemx .c++
 C@t{++} source file
 
+@itemx .m
+Objective-C source file
+
 @item .f
 @itemx .F
 Fortran source file
@@ -7774,7 +7782,7 @@ being set automatically by @value{GDBN}.
 @node Support
 @section Supported languages
 
-@value{GDBN} supports C, C@t{++}, Fortran, Java, assembly, and Modula-2.
+@value{GDBN} supports C, C@t{++}, Objective-C, Fortran, Java, assembly, and Modula-2.
 @c This is false ...
 Some @value{GDBN} features may be used in expressions regardless of the
 language you use: the @value{GDBN} @code{@@} and @code{::} operators,
@@ -7791,8 +7799,9 @@ books written on each of these languages
 language reference or tutorial.
 
 @menu
-* C::           C and C@t{++}
-* Modula-2::    Modula-2
+* C::                           C and C@t{++}
+* Objective-C::                 Objective-C             
+* Modula-2::                    Modula-2
 @end menu
 
 @node C
@@ -8309,7 +8318,84 @@ available choices, or to finish the type
 @xref{Completion,, Command completion}, for details on how to do this.
 @end table
 
-@node Modula-2
+@node Objective-C
+@subsection Objective-C
+
+This section provides information about some commands and command
+options that are useful for debugging Objective-C code.
+
+@menu
+* Method Names in Commands::    
+* The Print Command with Objective-C::  
+@end menu
+
+@node Method Names in Commands, The Print Command with Objective-C, Objective-C, Objective-C
+@subsubsection Method Names in Commands
+
+The following commands have been extended to accept Objective-C method
+names as line specifications:
+
+@itemize
+@item @code{clear}
+@item @code{break}
+@item @code{info line}
+@item @code{jump}
+@item @code{list}
+@end itemize
+
+For example, to set a breakpoint at the @code{create} instance method of 
+class @code{Fruit} in the program currently being debugged, enter:
+
+@example
+break -[Fruit create]
+@end example
+
+To list ten program lines around the @code{initialize} class method,
+enter:
+
+@example
+list +[NSText initialize]
+@end example
+
+In the current version of GDB, the plus or minus sign is required.  In
+future versions of GDB, the plus or minus sign will be optional, but you
+can use it to narrow the search.  It is also possible to specify just a
+method name:
+
+@example
+break create
+@end example
+
+You must specify the complete method name, including any colons.  If
+your program's source files contain more than one @code{create} method,
+you'll be presented with a numbered list of classes that implement that
+method.  Indicate your choice by number, or type @samp{0} to exit if
+none apply.
+
+As another example, to clear a breakpoint established at the
+@code{makeKeyAndOrderFront:} method of the @code{NSWindow} class, enter:
+
+@example
+clear -[NSWindow makeKeyAndOrderFront:]
+@end example
+
+@node The Print Command with Objective-C
+@subsubsection The Print Command With Objective-C
+
+The print command has also been extended to accept methods. For example:
+
+@example
+print -[object hash]
+@end example
+
+will tell gdb to send the -hash message to object and print the
+result. Also an additional command has been added, @code{print-object}
+or @code{po} for short, which is meant to print the description of an
+object. However, this command may only work with certain Objective-C
+libraries that have a particular hook function, called
+@code{_NSPrintForDebugger} defined.
+
+@node Modula-2,  , Objective-C, Support
 @subsection Modula-2
 
 @cindex Modula-2, @value{GDBN} support
@@ -8948,6 +9034,20 @@ outside of functions (i.e.@: excluding l
 Print the names and data types of all variables (except for local
 variables) whose names contain a match for regular expression
 @var{regexp}.
+
+@kindex info classes
+@item info classes
+@itemx info classes @var{regexp}
+Display all Objective-C classes in your program, or
+(with the @var{regexp} argument) all those matching a particular regular
+expression.
+
+@kindex info selectors
+@item info selectors
+@itemx info selectors @var{regexp}
+Display all Objective-C selectors in your program, or
+(with the @var{regexp} argument) all those matching a particular regular
+expression.
 
 @ignore
 This was never implemented.

[Ping/RFA]: ObjC Documentation

[Adam Fedor]

This patch hasn't been reviewed yet:

http://sources.redhat.com/ml/gdb-patches/2003-04/msg00542.htm

Adam Fedor wrote:
> 
> ------------------------------------------------------------------------
> 
> 2003-04-29  Adam Fedor  <fedor@gnu.org>
> 
> 	* gdb.texinfo: Add Objective-C documentation.
> 

Re: [Ping/RFA]: ObjC Documentation

[Eli Zaretskii]

> Date: Sat, 31 May 2003 21:52:41 -0600
> From: Adam Fedor <fedor@doc.com>
> 
> This patch hasn't been reviewed yet:
> 
> http://sources.redhat.com/ml/gdb-patches/2003-04/msg00542.htm

Sorry, my bad; I missed the original message somehow.

Here are my comments:

    +@itemx .m
    +Objective-C source file

This should be "@item .m", not @itemx.  @itemx is only used when you
have several table items which all share the same text, like this:

    @item foo
    @itemx bar
    @itemx baz
    Sample items for the same descriptive text.

    +The following commands have been extended to accept Objective-C method
    +names as line specifications:
    +
    +@itemize
    +@item @code{clear}
    +@item @code{break}
    +@item @code{info line}
    +@item @code{jump}
    +@item @code{list}
    +@end itemize

These need index entries for the special syntax of these commands
when debugging Objective-C programs.  Like this:

     @kindex clear@r{, and Objective-C}

Also, the general form of the extended commands is something I sorely
miss in this description.  Given the example:

    +@example
    +break -[Fruit create]
    +@end example

someone like me who doesn't speak fluent Objective-C is left wondering
what is "Fruit" and why do I need the `-' and the brackets.  Yes, I
know, some of that is explained further down, but a general form of
each command early on would both make the esamples more clear and
serve as an instant reminder for someone who just needs to see the
general rule.

Finally, please imagine that you are a user looking up the manual for
some specific issues pertinent to these features, and add index
entries for any issues users might wish to use to find the text you
wrote.

With those comments taken care of, the patch is approved.  Feel free
to ask if something in what I wrote is unclear.

Last, but not least: thanks for working on this!

Re: [Ping/RFA]: ObjC Documentation

[Adam Fedor]

[-- Attachment #1: Type: text/plain, Size: 352 bytes --]



Eli Zaretskii wrote:
>>Date: Sat, 31 May 2003 21:52:41 -0600
>>From: Adam Fedor <fedor@doc.com>
>>
>>This patch hasn't been reviewed yet:
>>
>>http://sources.redhat.com/ml/gdb-patches/2003-04/msg00542.htm
> 
> 
> Sorry, my bad; I missed the original message somehow.
> 
> Here are my comments:
> 

Thanks for the comments. Here's the final patch...


[-- Attachment #2: gdbdoc.patch --]
[-- Type: text/plain, Size: 6083 bytes --]

2003-06-06  Adam Fedor  <fedor@gnu.org>

        * gdb.texinfo: Add Objective-C documentation.

Index: doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.162
diff -u -p -r1.162 gdb.texinfo
--- doc/gdb.texinfo	8 May 2003 21:33:49 -0000	1.162
+++ doc/gdb.texinfo	7 Jun 2003 01:46:22 -0000
@@ -210,6 +210,10 @@ syntax.
 it may be necessary to refer to some variables with a trailing
 underscore.
 
+@cindex Objective-C
+@value{GDBN} can be used to debug programs written in Objective-C,
+using either the Apple/NeXT or the GNU Objective-C runtime.
+
 @menu
 * Free Software::               Freely redistributable software
 * Contributors::                Contributors to GDB
@@ -3180,7 +3184,8 @@ end
 @cindex overloading
 @cindex symbol overloading
 
-Some programming languages (notably C@t{++}) permit a single function name
+Some programming languages (notably C@t{++} and Objective-C) permit a 
+single function name
 to be defined several times, for application in different contexts.
 This is called @dfn{overloading}.  When a function name is overloaded,
 @samp{break @var{function}} is not enough to tell @value{GDBN} where you want
@@ -7487,6 +7492,9 @@ C source file
 @itemx .c++
 C@t{++} source file
 
+@item .m
+Objective-C source file
+
 @item .f
 @itemx .F
 Fortran source file
@@ -7762,7 +7770,7 @@ being set automatically by @value{GDBN}.
 @node Support
 @section Supported languages
 
-@value{GDBN} supports C, C@t{++}, Fortran, Java, assembly, and Modula-2.
+@value{GDBN} supports C, C@t{++}, Objective-C, Fortran, Java, assembly, and Modula-2.
 @c This is false ...
 Some @value{GDBN} features may be used in expressions regardless of the
 language you use: the @value{GDBN} @code{@@} and @code{::} operators,
@@ -7779,8 +7787,9 @@ books written on each of these languages
 language reference or tutorial.
 
 @menu
-* C::           C and C@t{++}
-* Modula-2::    Modula-2
+* C::                           C and C@t{++}
+* Objective-C::                 Objective-C             
+* Modula-2::                    Modula-2
 @end menu
 
 @node C
@@ -8297,7 +8306,100 @@ available choices, or to finish the type
 @xref{Completion,, Command completion}, for details on how to do this.
 @end table
 
-@node Modula-2
+@node Objective-C
+@subsection Objective-C
+
+This section provides information about some commands and command
+options that are useful for debugging Objective-C code.
+
+@menu
+* Method Names in Commands::    
+* The Print Command with Objective-C::  
+@end menu
+
+@node Method Names in Commands, The Print Command with Objective-C, Objective-C, Objective-C
+@subsubsection Method Names in Commands
+
+The following commands have been extended to accept Objective-C method
+names as line specifications:
+
+@kindex clear@r{, and Objective-C}
+@kindex break@r{, and Objective-C}
+@kindex info line@r{, and Objective-C}
+@kindex jump@r{, and Objective-C}
+@kindex list@r{, and Objective-C}
+@itemize
+@item @code{clear}
+@item @code{break}
+@item @code{info line}
+@item @code{jump}
+@item @code{list}
+@end itemize
+
+A fully qualified Objective-C method name is specified as
+
+@example
+-[Class methodName]
+@end example
+
+where the minus sign is used to indicate an instance method and a plus
+sign (not shown) is used to indicate a class method. The
+class name @var{Class} and method name @var{methoName} are enclosed in
+brackets, similar to the way messages are specified in Objective-C source
+code. For example, to set a breakpoint at the @code{create} instance method of 
+class @code{Fruit} in the program currently being debugged, enter:
+
+@example
+break -[Fruit create]
+@end example
+
+To list ten program lines around the @code{initialize} class method,
+enter:
+
+@example
+list +[NSText initialize]
+@end example
+
+In the current version of GDB, the plus or minus sign is required.  In
+future versions of GDB, the plus or minus sign will be optional, but you
+can use it to narrow the search.  It is also possible to specify just a
+method name:
+
+@example
+break create
+@end example
+
+You must specify the complete method name, including any colons.  If
+your program's source files contain more than one @code{create} method,
+you'll be presented with a numbered list of classes that implement that
+method.  Indicate your choice by number, or type @samp{0} to exit if
+none apply.
+
+As another example, to clear a breakpoint established at the
+@code{makeKeyAndOrderFront:} method of the @code{NSWindow} class, enter:
+
+@example
+clear -[NSWindow makeKeyAndOrderFront:]
+@end example
+
+@node The Print Command with Objective-C
+@subsubsection The Print Command With Objective-C
+
+The print command has also been extended to accept methods. For example:
+
+@example
+print -[object hash]
+@end example
+
+@cindex print an Objective-C object description
+will tell gdb to send the -hash message to object and print the
+result. Also an additional command has been added, @code{print-object}
+or @code{po} for short, which is meant to print the description of an
+object. However, this command may only work with certain Objective-C
+libraries that have a particular hook function, called
+@code{_NSPrintForDebugger} defined.
+
+@node Modula-2,  , Objective-C, Support
 @subsection Modula-2
 
 @cindex Modula-2, @value{GDBN} support
@@ -8936,6 +9038,20 @@ outside of functions (i.e.@: excluding l
 Print the names and data types of all variables (except for local
 variables) whose names contain a match for regular expression
 @var{regexp}.
+
+@kindex info classes
+@item info classes
+@itemx info classes @var{regexp}
+Display all Objective-C classes in your program, or
+(with the @var{regexp} argument) all those matching a particular regular
+expression.
+
+@kindex info selectors
+@item info selectors
+@itemx info selectors @var{regexp}
+Display all Objective-C selectors in your program, or
+(with the @var{regexp} argument) all those matching a particular regular
+expression.
 
 @ignore
 This was never implemented.

Re: [Ping/RFA]: ObjC Documentation

[Eli Zaretskii]

> Date: Fri, 06 Jun 2003 19:49:55 -0600
> From: Adam Fedor <fedor@doc.com>
> 
> Thanks for the comments. Here's the final patch...

Approved, but please make these minor corrections:

> +@cindex Objective-C
> +@value{GDBN} can be used to debug programs written in Objective-C,
> +using either the Apple/NeXT or the GNU Objective-C runtime.

The index entry "@cindex Objective-C" should not be here, but where
the features specific to Objective-C are described:

> +@node Objective-C
> +@subsection Objective-C

here.

> +A fully qualified Objective-C method name is specified as
> +
> +@example
> +-[Class methodName]
> +@end example

Please change this to the following:

 +@example
 +-[@var{Class} @var{methodName}]
 +@end example

"Class" and "methodName" are meta-syntactic variables (they stand for
something else), and you use them, correctly, inside @var{} in the
text that explains this notation.  So they should be in @var{} here as
well.

With these two changes, please commit the patch.  Thanks!

Re: [Ping/RFA]: ObjC Documentation

[Andrew Cagney]

> Please change this to the following:
> 
>  +@example
>  +-[@var{Class} @var{methodName}]
>  +@end example

Pss.  ``@smallexample'' :-)

Andrew