Re: [PATCH] Add Guile JIT reader interface

[Eli Zaretskii <eliz at gnu dot org>]

> From: Andy Wingo <wingo@igalia.com>
> Date: Mon, 23 Feb 2015 18:29:44 +0100
> 
> This patch lets users unwind the stack from Guile.  It is built on the
> custom JIT debug info reader API.  Thoughts?

Thanks.  A few comments about the documentation parts.

> +@var{get-frame-id} computes and returns a frame ID, which is a pair
> +whose car is a code address and whose cdr is a frame pointer.  A frame

I think "car" and "cdr" should be in @code (they are symbols).

> +@deffn {Scheme Procedure} make-jit-reader-block name begin end children
> +Construct and return a new JIT reader block describing the code region
> +between @var{begin} and @var{end}, both integers.  @var{name} is a

The usual question that comes to mind when I read about such
interfaces is whether the region includes END or not.  How about
stating that explicitly?

> +If the value of the register is not known, this function returns
> +@code{#f}.  Otherwise, it returns the value as a bytevector.

Why a bytevector?  Isn't the value a single scalar?

> +@deffn {Scheme Procedure} jit-reader-write-register register value
> +Set the previous value of @var{register} to @var{value}.  As in
> +@code{jit-reader-read-register}, this function may only be called
> +within an @code{unwind-frame} or @code{get-frame-info} callback.
> +@var{register} may be a string or an integer, and @var{value} may be a
> +bytevector or @code{#f}.

I think this begs for describing the semantics of writing #f into a
register.  I don't think it's self-explanatory.

The log message promises a NEWS entry, but I didn't see diffs for
that.

Otherwise, OK for the documentation.