Front page | perl.perl5.porters |
Postings from May 2013
On 04/30/2013 07:16 PM, Tony Cook wrote:
> On Tue, Apr 30, 2013 at 08:33:03AM -0600, Karl Williamson wrote:
>> Quite a few functions in the API are marked as experimental. I
>> think each should be highlighted by having that fact the first thing
>> in the entry. As an example, here's what a typical entry would look
>> like:
>>
>> av_create_and_push
>> NOTE: this function is experimental and may change or be
>> removed without notice.
>>
>> Push an SV onto the end of the array, creating the array if
>> necessary. A small internal helper function to remove a
>> commonly duplicated idiom.
>>
>> void av_create_and_push(AV **const avp,
>> SV *const val)
>>
>> Are there any objections?
>
> This makes sense to me.
>
> Tony
>
I may not have been clear in my original statement. No text is being
added or removed, just moved around. Currently, the NOTE comes at the
end, just before the function signature. That's probably not an issue
where the description is as short as this example, but in a
multi-paragraph description, I think that the reader may skip over to
the signature, missing the NOTE. To make it perfectly clear, I hope,
here's what blead's perlapi says:
av_create_and_push
Push an SV onto the end of the array, creating the array if necessary.
A small internal helper function to remove a commonly duplicated idiom.
NOTE: this function is experimental and may change or be
removed without notice.
void av_create_and_push(AV **const avp,
SV *const val)
Thread Previous
|
Thread Next