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
