Front page | perl.perl5.porters |
Postings from August 2016
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. > > +1Thread Previous | Thread Next