Re: Contribution to Perldoc for TestLib module in Postgres

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.

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