Re: Small documentation feature request

[Rici Lake]

LGTM. Thanks.

El mar., 30 jun. 2020 a las 12:41, Akim Demaille (<akim@lrde.epita.fr>)
escribió:

> Hi Rici!
>
> > Le 30 juin 2020 à 18:23, Rici Lake <ricilake@gmail.com> a écrit :
> >
> > Hi, Akim and bisonistas,
> >
> > This came up today on SO:
> >
> https://stackoverflow.com/questions/62658368/unknown-type-yypcontext-t-in-bison
> .
>
> Thanks for pointing this out.
>
> > The user complained that their attempt to declare `yyreport_syntax_error`
> > failed because `yypcontext_t` was not defined. (The declaration was put
> in
> > a `%{` code section in the prologue.)
> >
> > That seems to be expected, since the structure is not declared until
> after
> > all the prologue code has been included, and furthermore
> > yyreport_syntax_error is declared as `static`, implying that it must be
> > defined in the bison input file in the final code section.
>
> Yes, all this is in the *.c file only, nothing in the header file.
>
> > However, the manual does not mention this fact, and I think that it is
> not
> > immediately obvious. It would, IMHO, be a good idea to put a small note
> > about that in the manual chapter which describes that function.
>
> You're right.  WDYT about this?
>
> commit fd022d632d2b77288769e410f3332ecc44d45ba7
> Author: Akim Demaille <akim.demaille@gmail.com>
> Date:   Tue Jun 30 19:35:45 2020 +0200
>
>     doc: clarify that the pcontext interface is *.c only
>
>     Reported by Rici Lake.
>     https://lists.gnu.org/r/bug-bison/2020-06/msg00054.html
>
>     * doc/bison.texi (Syntax Error Reporting Function): Make it clear that
>     this is not exported.
>     Remove C++ details that landed in the C doc.
>
> diff --git a/doc/bison.texi b/doc/bison.texi
> index 985b1d7c..02676190 100644
> --- a/doc/bison.texi
> +++ b/doc/bison.texi
> @@ -7619,7 +7619,11 @@ Declarations}), then the parser no longer passes
> syntax error messages to
>  @code{yyerror}, rather it delegates that task to the user by calling the
>  @code{yyreport_syntax_error} function.
>
> -@deftypefun int yyreport_syntax_error (@code{const yypcontext_t
> *}@var{ctx})
> +The following functions and types are ``@code{static}'': they are defined
> in
> +the implementation file (@file{*.c}) and available only from there.  They
> +are meant to be used from the grammar's epilogue.
> +
> +@deftypefun {static int} yyreport_syntax_error (@code{const yypcontext_t
> *}@var{ctx})
>  Report a syntax error to the user.  Return 0 on success, @code{YYENOMEM}
> on
>  memory exhaustion.  Whether it uses @code{yyerror} is up to the user.
>  @end deftypefun
> @@ -7654,16 +7658,16 @@ typedef enum yysymbol_kind_t yysymbol_kind_t;
>  @end example
>  @end deffn
>
> -@deftypefun {yysymbol_kind_t} yypcontext_token (@code{const yypcontext_t
> *}@var{ctx})
> +@deftypefun {static yysymbol_kind_t} yypcontext_token (@code{const
> yypcontext_t *}@var{ctx})
>  The ``unexpected'' token: the symbol kind of the lookahead token that
> caused
>  the syntax error.  Return @code{YYSYMBOL_YYEMPTY} if there is no
> lookahead.
>  @end deftypefun
>
> -@deftypefun {YYLTYPE *} yypcontext_location (@code{const yypcontext_t
> *}@var{ctx})
> +@deftypefun {static YYLTYPE *} yypcontext_location (@code{const
> yypcontext_t *}@var{ctx})
>  The location of the syntax error (that of the unexpected token).
>  @end deftypefun
>
> -@deftypefun int yypcontext_expected_tokens (@code{const yypcontext_t
> *}ctx, @code{yysymbol_kind_t} @var{argv}@code{[]}, @code{int} @var{argc})
> +@deftypefun {static int} yypcontext_expected_tokens (@code{const
> yypcontext_t *}ctx, @code{yysymbol_kind_t} @var{argv}@code{[]},
> @code{int} @var{argc})
>  Fill @var{argv} with the expected tokens, which never includes
>  @code{YYSYMBOL_YYEMPTY}, @code{YYSYMBOL_YYerror}, or
>  @code{YYSYMBOL_YYUNDEF}.
> @@ -7681,10 +7685,8 @@ If @var{argv} is null, return the size needed to
> store all the possible
>  values, which is always less than @code{YYNTOKENS}.
>  @end deftypefun
>
> -@deftypefun {@r{string type}} yysymbol_name (@code{symbol_kind_t}
> @var{symbol})
> +@deftypefun {static const char *} yysymbol_name (@code{symbol_kind_t}
> @var{symbol})
>  The name of the symbol whose kind is @var{symbol}, possibly translated.
> -Depending on the options, may return a @code{const char*} or a
> -@code{std::string}.
>  @end deftypefun
>
>  A custom syntax error function looks as follows.  This implementation is
> @@ -7692,7 +7694,7 @@ inappropriate for internationalization, see the
> @file{c/bistromathic}
>  example for a better alternative.
>
>  @example
> -int
> +static int
>  yyreport_syntax_error (const yypcontext_t *ctx)
>  @{
>    int res = 0;
>
>
>