Re: [PATCH 3/4] Adds documentation.

[Eli Zaretskii <eliz@gnu.org>]

> From: Sanjoy Das <sanjoy@playingwithpointers.com>
> Cc: Sanjoy Das <sanjoy@playingwithpointers.com>
> Date: Sun, 24 Jul 2011 21:33:46 +0530
> 
> Adds some basic documentation to gdb.texinfo about the new JIT reader functionality. This should be a good entry point for developers writing parsers for the debug info their JIT compiler generates.

Thanks.

> gdb/ChangeLog
> 	* gdb.texinfo: Some documentation about the new JIT debug info reader functionality.

This should state the name(s) of the new node(s), in the same format
as gdb/ChangeLog documents functions, as if each node were a function.

> +@node Custom Object File Format

You cannot add a node without also adding it to the menu in its parent
(which happens to be "JIT Interface" in this case).  I guess you
didn't actually say "make info", because I don't think it would have
worked for you.

> +@section Custom Object File Format

As a general rule, each @section should have a @cindex entry whose
text is identical to the section name, but with all lower-case
letters.

> +Generating debug information in native file formats (like ELF or COFF) can become an overkill for JIT compilers; especially if all the debug info is used for displaying a meaningful backtrace. The issue can be resolved by having the JIT writers decide on a debug info format and provide a third-party reader that parses the debug info generated by the JIT compiler. This section gives an overview on writing such a parser. More details can be found in the file @code{gdb/jit-reader.h.in}.

First, please don't make such long lines, they make reading harder.

Second, please leave 2 spaces after a period that ends a sentence.

And third, "gdb/jit-reader.h.in" is a file, so it should have the
@file markup, not @code.

> +The reader is implemented as a shared object. GDB, when trying to read the debug information generated by a JIT compiler, looks for such shared objects in a special, pre-configured, directory. If such a (conforming) shared object is found, it is dynamically loaded and used to parse the debug info.

Please use "@value{GDBN}" instead of a literal "GDB".  That allows to
change the name in only one place, if someone wants to produce a
manual for a customized GDB that has a different name.

> +@node Writing A Parser
> +@subsection Writing A Parser

There should be a @menu in the previous node before you can use a
@subsection here.

Please add an index entry here, something like

  @cindex JIT parser
  @cindex writing JIT parsers

> +The parser needs to include @code{jit-reader.h}, which defines the required structures, macros and functions.
                               ^^^^^
@file

> +@node Elements Of @code{jit-reader.h}

A @node cannot use @-commands.  So just "Elements of jit-reader.h"

Also, this node has to appear in a menu, see above.

> +@subsubsection Elements Of @code{jit-reader.h}
                              ^^^^^
@file

> +After the plugin is loaded, GDB looks for the function @code{gdb_init_reader}. The prototype of the function (also included in @code{jit-reader.h}) is:
                                                  ^^^^^
@file

> +@node The API

Should be in a menu.

> +The plugin provides an API for creating symbol files (which GDB will use to, for instance, display function names in the backtrace) and implementing a frame unwinder.
                                                               ^^^
@value{GDBN}

> +@strong{Symbol Reading}

If this is supposed to be a heading, please use @heading.

> +The @code{read} function in @code{struct gdb_reader_funcs} is called to read in the debug info emitted by the JIT compiler and create the appropriate symbol tables. To keep the API clean and stable, GDB's internal structures are not exposed. Instead, a @code{struct} full of function pointers are passed to @code{read} which it is supposed to use to construct the symbol table.

Again, @value{GDBN}.