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

Re: Internals:: undocumented

Thread Previous | Thread Next
James E Keenan
August 8, 2016 11:21
Re: Internals:: undocumented
Message ID:
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" <> 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.


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