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

Re: Internals:: undocumented

Thread Previous | Thread Next
From:
James E Keenan
Date:
August 8, 2016 11:21
Subject:
Re: Internals:: undocumented
Message ID:
20160808112108.21178.qmail@lists-nntp.develooper.com
On 08/08/2016 06:51 AM, Dave Mitchell wrote:
> On Sun, Aug 07, 2016 at 12:25:14PM +0200, demerphq wrote:
>> On 7 Aug 2016 11:34, "Sawyer X" <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.
>
> 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
>    compatibility);
> 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.
>
>

+1


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