Front page | perl.perl5.porters |
Postings from August 2016
Re: Internals:: undocumented
Thread Previous
|
Thread Next
From:
demerphq
Date:
August 14, 2016 12:17
Subject:
Re: Internals:: undocumented
Message ID:
CANgJU+VZzA231xGK1eHdCYf9sRoyS3_Cs=W7QuOObprN1q0RYw@mail.gmail.com
On 13 August 2016 at 20:09, Sawyer X <xsawyerx@gmail.com> wrote:
> [Top-posted].
>
> We have quite a few questions that we raised here, but I'll focus on two:
>
> 1. Should Internals:: be documented?
>
> 2. Should Internals:: namespace exist?
>
> I agree that removing Internals:: namespace makes sense, in the steps
> Yves suggests, but along Aristotle's direction ("poor person stuck with
> the code" is quite the compelling argument, IMHO). However, if we want
> to make the core more approachable and more understandable (both to
> current hackers and new hackers), documenting what we have (even if only
> for internal use) is on the table.
> Thus, the first question can be rephrased as "Should the functions [only
> currently] in Internals:: be documented?" - I would say yes. Then
> slapping a nice "We do not assure compatibility of these functions. Use
> at your own risk. If they provide something you cannot do otherwise or
> do not know how, let us know."
>
> When someone (outside core) uses an internal functions, they might not
> know how to do it properly (Lack of documentation? Bad documentation?)
> or they need an interface that does not officially exist (and perhaps we
> should add it) or they are doing something wrong (perhaps also a
> documentation problem on how to do it properly). At least the first two
> we can try and address.
>
Ok. Fair enough.
I have pushed a patch series which moves the Hash::Util related stuff
out of universal.c, and removes hv_clear_placeholders() from
Internals. I am pretty sure this should not affect anything sane.
I have also pushed a patch which adds lib/Internals.pod to document
the remaining two functions in the Internals namespace.
I expect other will want to improve and edit my prose. I didn't use
exactly the language you used here for instance and maybe it should.
But now we have something to start patching.
$ git log -5 --oneline --stat
cb19816 first step to documenting the Internals namespace
MANIFEST | 1 +
Porting/Maintainers.pl | 1 +
Porting/Maintainers.pm | 4 ++--
lib/Internals.pod | 69
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
sv.h | 19 ++++++++++++++++++-
5 files changed, 91 insertions(+), 3 deletions(-)
48c0e89 Move hash introspection routines into Hash::Util/Util.xs and
out of universal.c
ext/Hash-Util/Util.xs | 6 ++++--
t/op/coreamp.t | 1 +
t/op/each.t | 1 +
t/op/hash.t | 2 +-
t/op/sub_lval.t | 1 +
universal.c | 65
-----------------------------------------------------------------
6 files changed, 8 insertions(+), 68 deletions(-)
e6d22c5 s/XS_hash_util_/XS_Hash_Util_/g
universal.c | 18 +++++++++---------
1 file changed, 9 insertions(+), 9 deletions(-)
2b9dd39 move a declaration so that the Internals:: functions are
grouped together
universal.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
10f9b9b move Internals::hv_clear_placeholders() to
Hash::Util::_clear_placeholders()
ext/Hash-Util/Util.xs | 10 ++++++++++
ext/Hash-Util/lib/Hash/Util.pm | 27 ++++++++++++++++++++++-----
t/lib/universal.t | 2 --
t/re/subst.t | 2 +-
universal.c | 15 ---------------
5 files changed, 33 insertions(+), 23 deletions(-)
Cheers,
Yves
Thread Previous
|
Thread Next