Front page | perl.perl5.porters |
Postings from August 2016
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. -- Any [programming] language that doesn't occasionally surprise the novice will pay for it by continually surprising the expert. -- Larry WallThread Previous | Thread Next