Re: Contribution to Perldoc for TestLib module in Postgres

On 7/10/19 9:38 AM, Alvaro Herrera wrote:
> On 2019-Apr-11, Iwata, Aya wrote:
>
>> In the above document, why not write a description after the function name?
>> I think it is better to write the function name first and then the description.
>> In your code;
>>   #Checks if all the tests passed or not
>>  all_tests_passing()
>>
>> In my suggestion;
>>   all_tests_passing()
>>   Checks if all the tests passed or not
> Yeah, so there are two parts in the submitted patch: first the synopsis
> list the methods using this format you describe, and later the METHODS
> section lists then again, using your suggested style.  I think we should
> do away with the long synopsis -- maybe keep it as just the "use
> TestLib" line, and then let the METHODS section list and describe the
> methods.
>
>> And some functions return value. How about adding return information
>> to the above doc?
> That's already in the METHODS section for some of them.  For example:
>
>     all_tests_passing()
>         Returns 1 if all the tests pass. Otherwise returns 0
>
> It's missing for others, such as "tempdir".
>
> In slurp_file you have this:
>   Opens the file provided as an argument to the function in read mode(as
>   indicated by <).
> I think the parenthical comment is useless; remove that.
>
> Please break long source lines (say to 78 chars -- make sure pgperltidy
> agrees), and keep some spaces after sentence-ending periods and other
> punctuation.
>


I've fixed the bitrot and some other infelicities on this patch. It's
not commitable yet but I think it's more reviewable.


cheers


andrew


-- 
Andrew Dunstan                https://www.2ndQuadrant.com
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services