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

Re: Internals:: undocumented

Thread Previous | Thread Next
From:
Karl Williamson
Date:
August 7, 2016 17:09
Subject:
Re: Internals:: undocumented
Message ID:
737c5cc1-a9c3-a435-4cab-a02cb9da7f31@khwilliamson.com
On 08/07/2016 04:25 AM, demerphq wrote:
> On 7 Aug 2016 11:34, "Sawyer X" <xsawyerx@gmail.com
> <mailto:xsawyerx@gmail.com>> 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.
>
> Yvez
>

Hi Yvez,

They should be documented in the source or perlguts or perlhacktips, so 
people like me would know about their existence.  This is the first I've 
heard of them, and I've been working on the core for coming up 7 years 
now.  There is a difference between encouraging external use and letting 
porters know the existence of things that could make their lives easier, 
without them having to scrutinize every source file we ship.  I keep 
discovering things that I didn't know about.  Today I saw that you can 
add -v to harness, for example.

Thread Previous | Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About