develooper Front page | perl.perl5.porters | Postings from August 2016

Re: Internals:: undocumented

Thread Previous | Thread Next
Dave Mitchell
August 8, 2016 10:51
Re: Internals:: undocumented
Message ID:
On Sun, Aug 07, 2016 at 12:25:14PM +0200, demerphq wrote:
> On 7 Aug 2016 11:34, "Sawyer X" <> wrote:
> >
> > On 08/06/2016 03:39 PM, Tony Cook wrote:
> > > On Sat, Aug 06, 2016 at 09:05:23AM -0400, James E Keenan wrote:
> > >> What is Internals?
> > > Internals is deliberately undocumented, unsupported.
> >
> > Not documenting as a form of keeping possible users away feels like
> > security by obscurity. Documentation should not imply support. We can
> > document it clearly for other core developers and note *very* clearly
> > that it is unsupported.
> I don't agree. We document indirectly those functions that are intended to
> be user serviceable. The rest imo should not be documented because they
> should not exist but do because they are needed to test perl. Furthermore
> they are typically documented at the XS or perl internals level,  and all
> the perl level functions do is expose internals routines.
> I also think that if we are going to document them we should move them to
> better namespace.

We already document non-API C functions - see pod/perlintern.pod - so
there is a precedent for documenting non-API functions. Personally I think
we should

1) Keep the Internals:: namespace as-is;
2) If there's something in that namespace which is general-purpose enough
   that it deserves to be part of the API, then give it a new name in
   a different namespace (probably maintaining the old name for
3) Create pod/Internals.pod which explains what the purpose of the
   Internals:: namespace is for, the fact that non-core isn't allowed to
   use it, and that the (non-)API can change without notice; then
   document each function in the Internals:: namespace - even if its
   just to say that its just a perl wrapper for a C function.

Any [programming] language that doesn't occasionally surprise the
novice will pay for it by continually surprising the expert.
   -- Larry Wall

Thread Previous | Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About