From @bulk88

Created by @bulk88

perlapi shows prototypes to the *pvs family of functions, like newSVpvs
________________________________________________________________
  newSVpvs
  Like "newSVpvn", but takes a literal string instead of a
  string/length pair.

  SV* newSVpvs(const char* s)
________________________________________________________________

another example is sv_setpvs
_______________________________________________________________
sv_setpvs
Like sv_setpvn , but takes a literal string instead of a string/length pair.

  void sv_setpvs(SV* sv, const char* s)
_______________________________________________________________

The 2 quotes are from 2 different pod viewers.

The description says "literal string", but the prototype makes you think
you can pass a char * if you don't read the description. I'm not sure
how this can be made better. would a "const char s []" be any better?
would that work embed.fnc and actual C code? Should "literal string" be
reworded in the *pvs funcs' POD to make it more clear it is not a char *?

One idea I have is

  SV* newSVpvs("literal string")

Overall, the *pvs functions POD are just unclear to someone new.

Flags:
     category=docs
     severity=low

Site configuration information for perl 5.17.7:

Configured by Owner at Sun Dec 16 13:25:34 2012.

Summary of my perl5 (revision 5 version 17 subversion 7 patch blead 
2012-12-06.16:42:20 93a641ae382638ffd1980378be4810244d04f4b0 
v5.17.6-186-g93a641a) configuration:
   Snapshot of: 93a641ae382638ffd1980378be4810244d04f4b0
   Platform:
     osname=MSWin32, osvers=5.1, archname=MSWin32-x86-multi-thread
     uname=''
     config_args='undef'
     hint=recommended, useposix=true, d_sigaction=undef
     useithreads=define, usemultiplicity=define
     useperlio=define, d_sfio=undef, uselargefiles=define, usesocks=undef
     use64bitint=undef, use64bitall=undef, uselongdouble=undef
     usemymalloc=n, bincompat5005=undef
   Compiler:
     cc='cl', ccflags ='-nologo -GF -W3 -MD -Zi -DNDEBUG -O1 -GL -G7 
-DWIN32 -D_CONSOLE -DNO_STRICT  -DPERL_TEXTMODE_SCRIPTS 
-DPERL_IMPLICIT_CONTEXT -DPERL_IMPLICIT_SYS -DUSE_PERLIO 
-D_USE_32BIT_TIME_T',
     optimize='-MD -Zi -DNDEBUG -O1 -GL -G7',
     cppflags='-DWIN32'
     ccversion='13.10.6030', gccversion='', gccosandvers=''
     intsize=4, longsize=4, ptrsize=4, doublesize=8, byteorder=1234
     d_longlong=undef, longlongsize=8, d_longdbl=define, longdblsize=8
     ivtype='long', ivsize=4, nvtype='double', nvsize=8, 
Off_t='__int64', lseeksize=8
     alignbytes=8, prototype=define
   Linker and Libraries:
     ld='link', ldflags ='-nologo -nodefaultlib -debug -opt:ref,icf 
-ltcg  -libpath:"c:\perl517\lib\CORE"  -machine:x86'
     libpth="C:\Program Files\Microsoft Visual Studio .NET 2003\VC7\lib"
     libs=oldnames.lib kernel32.lib user32.lib gdi32.lib winspool.lib 
comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib 
netapi32.lib uuid.lib ws2_32.lib mpr.lib winmm.lib  version.lib 
odbc32.lib odbccp32.lib comctl32.lib msvcrt.lib
     perllibs=oldnames.lib kernel32.lib user32.lib gdi32.lib 
winspool.lib  comdlg32.lib advapi32.lib shell32.lib ole32.lib 
oleaut32.lib  netapi32.lib uuid.lib ws2_32.lib mpr.lib winmm.lib 
version.lib odbc32.lib odbccp32.lib comctl32.lib msvcrt.lib
     libc=msvcrt.lib, so=dll, useshrplib=true, libperl=perl517.lib
     gnulibc_version=''
   Dynamic Linking:
     dlsrc=dl_win32.xs, dlext=dll, d_dlsymun=undef, ccdlflags=' '
     cccdlflags=' ', lddlflags='-dll -nologo -nodefaultlib -debug 
-opt:ref,icf -ltcg  -libpath:"c:\perl517\lib\CORE"  -machine:x86'

Locally applied patches:



@INC for perl 5.17.7:
     C:/perl517/site/lib
     C:/perl517/lib
     .


Environment for perl 5.17.7:
     HOME (unset)
     LANG (unset)
     LANGUAGE (unset)
     LD_LIBRARY_PATH (unset)
     LOGDIR (unset)
     PATH=C:\perl517\bin;C:\Program Files\Microsoft Visual Studio .NET 
2003\Common7\IDE;C:\Program Files\Microsoft Visual Studio .NET 
2003\VC7\BIN;C:\Program Files\Microsoft Visual Studio .NET 
2003\Common7\Tools;C:\Program Files\Microsoft Visual Studio .NET 
2003\Common7\Tools\bin\prerelease;C:\WINDOWS\system32;C:\WINDOWS;C:\WINDOWS\system32\wbem;
     PERL_BADLANG (unset)
     SHELL (unset)

From zefram@fysh.org

I concur that the use of a "const char *" type for these parameters
is misleading. In fact, showing any function prototype is misleading,
because these are macros and cannot be implemented as functions.
In commit 1568d13 I've changed it so
that these parameters are shown with a string literal in place of a type,
which should be clear enough. For example, perlapi now shows

  SV** hv_fetchs(HV* tb, "literal string" key,
  I32 lval)

I also removed the inaccurate words "NUL-terminated" from the prose
descriptions of these parameters.

-zefram

The RT System itself - Status changed from 'new' to 'open'

From @xsawyerx

On 11/12/2017 07​:10 AM, Zefram wrote​:

I concur that the use of a "const char *" type for these parameters
is misleading. In fact, showing any function prototype is misleading,
because these are macros and cannot be implemented as functions.
In commit 1568d13 I've changed it so
that these parameters are shown with a string literal in place of a type,
which should be clear enough. For example, perlapi now shows

                   SV\*\*    hv\_fetchs\(HV\* tb\, "literal string" key\,
                                     I32 lval\)

I think it would be good to have it say what "literal string" refers to,
or to have an example. That could help clarify how one could use it,
because when someone wants to send something, they are probably getting
it from a variable and will not understand which variable type is
"literal string" (though they could infer/guess/assume).

From zefram@fysh.org

Sawyer X wrote​:

I think it would be good to have it say what "literal string" refers to,

It does. The prose of that very perlapi entry says

  Like "hv_fetch", but takes a literal string instead of a
  string/length pair.

This ticket started by considering someone who glances at the prototype
and *hasn't* read the prose. Apart from the nonsensical reference to
"NUL-terminated" literals, the prose was already fine.

-zefram

@cpansprout - Status changed from 'open' to 'pending release'

From @khwilliamson

Thank you for filing this report. You have helped make Perl better.

With the release yesterday of Perl 5.28.0, this and 185 other issues have been
resolved.

Perl 5.28.0 may be downloaded via​:
https://metacpan.org/release/XSAWYERX/perl-5.28.0

If you find that the problem persists, feel free to reopen this ticket.

@khwilliamson - Status changed from 'pending release' to 'resolved'