Re: Small documentation feature request

[Akim Demaille]

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;