This is the mail archive of the gdb-patches@sourceware.org mailing list for the GDB project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: Python pretty-printing [2/6]


> Cc: gdb-patches@sourceware.org
> From: Tom Tromey <tromey@redhat.com>
> Date: Thu, 02 Apr 2009 18:47:16 -0600
> 
> 2009-04-01  Tom Tromey  <tromey@redhat.com>
> 	    Thiago Jung Bauermann  <bauerman@br.ibm.com>
> 	    Phil Muldoon  <pmuldoon@redhat.com>
> 
> 	* gdb.texinfo (Python API): Update.
> 	(Auto-loading): New node.
> 	(Objfiles In Python): New node.

Thanks.  I have several comments about the docs part:

> +@node Auto-loading
> +@subsubsection Auto-loading

Suggest a @cindex entry here, something like "auto-loading, Python".

> +When a new object file (@pxref{Objfiles In Python}) is read (for

Is the cross-reference to "Objfiles in Python" really useful here?
Loading object files has nothing to do with Python; the section you
refer to describes Python-specific features related to object files,
but those features seem to have nothing to do with auto-loading.  Did
I miss something?

If there no real relation between these two sections, I'd prefer to
remove the xref.  When I read a manual and it gives me a
cross-reference, I always assume that the cross-reference is
important, and go there to see what it says.  If it says nothing
appropriate, my time and attention are lost.

> +                           @value{GDBN} will look for a file named by
> +adding @samp{-gdb.py} to the object file's real name (the name formed
> +after following all symlinks and resolving @code{.} and @code{..}
> +components).

I suggest to rephrase this as follows:

  @value{GDBN} will look for a file named @file{@var{objfile}-gdb.py},
  where @var{objfile} is the object file's real name, formed by
  following all symlinks and resolving @file{.} and @file{..}
  components.

This tells the reader what the file name is, instead of explaining how
it is constructed.  I think the result is more clear.

Btw, the above description of what ``real name'' is seems inaccurate,
because the code actually calls `gdb_realpath', so the result is
actually an absolute file name, right?

> +If this file does not exist, and if the parameter
> +@code{debug-file-directory} is set, then @value{GDBN} will append the
> +object file's real name to the value of this parameter, and try again.

Again, I think it's better not to explain how the file's name is
created, but give its form and tell what are the components.  There's
another instance of that below.  Could you rephrase them all along the
above lines?

Also, what is debug-file-directory?  If it is documented somewhere, a
cross-reference here would be beneficial.

> +Finally, if this file does not exist, then @value{GDBN} will look in
> +subdirectory of @code{gdb_datadir} (whose value is available from
> +@code{maint show gdb_datadir}).
         ^^^^^^^^^^^^^^^^^^^^^^
Please add a cross-reference to where you describe this command.

>  Specifically, @value{GDBN} will take
> +the value of @code{gdb_datadir}, append @samp{python/auto-load}, and
> +then append the object file's real name.

Please use @file for files, not @samp.

> +Also, if a separate debug file is used,

Please add another cross-reference, to where we describe separate
debug file.

>                                          @value{GDBN} will look for the
> +@samp{-gdb.py} file both in the directory associated with the
> +application and the directory associated with the separate debug file.

Is this true for all 3 file names GDB tries, or only for some (the
first one?)?  Either way, I think we should tell that explicitly.

> +When reading a @samp{-gdb.py} file, @value{GDBN} sets the ``current
> +objfile''.  This is available via the @code{gdb.current_objfile}
> +function.  This can be useful for registering objfile-specific
> +pretty-printers.

Now, _this_ is where the cross-reference to "Objfiles in Python" would
be handy.

Also, you use "@samp{-gdb.py} file" quite a lot, so I think we should
invent a special term for it.  How about "autoloaded Python file"?

> +This feature is useful for supplying application-specific debugging
> +commands and scripts.  It can be disabled using @code{maint set python
> +auto-load}.

A cross-reference here, to where the command is documented would be
good.  Or maybe just document it here ('cause I don't think it's
documented anywhere else in your patches).

> +@cindex python objfiles

There are no "python objfiles", right?  I think it's better to use
something like "objfiles, access from Python".

> +@tindex gdb.Objfile
> +@tindex Objfile

We still don't have a @syncodeindex for @tindex, so if you want to use
it, please add that directive.

> +@value{GDBN} loads symbols for an inferior from various
> +symbol-containing files.  These include the primary executable file,
> +any shared libraries used by the inferior, and any separate debug info
> +files.  @value{GDBN} calls these symbol-containing files
> +@dfn{objfiles}.

It would be good to have cross-reference here to where the related GDB
features are described.

> +@defivar Objfile pretty_printers
> +The @code{pretty_printers} attribute is used to look up
> +pretty-printers by type.  This is a dictionary which maps regular
> +expressions (strings) to pretty-printing objects.

I think we want a cross-reference here to where pretty-printing is
described.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]