develooper Front page | perl.perl5.porters | Postings from May 2013

Re: Any objections to moving the perlapi's "NOTE: this functionis experimental" to the beginning of its entry

Thread Previous | Thread Next
From:
Karl Williamson
Date:
May 1, 2013 01:36
Subject:
Re: Any objections to moving the perlapi's "NOTE: this functionis experimental" to the beginning of its entry
Message ID:
51807195.9060205@khwilliamson.com
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


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About