On Tue, Feb 23, 2016 at 12:29 AM, Alvaro Herrera <alvherre@2ndquadrant.com> wrote: > Craig Ringer wrote: > >> > +=pod >> > + >> > +=head2 Set up a node >> > pod format... Do we really want that? Considering that those modules >> > are only aimed at being dedicated for in-core testing, I would say no. >> >> If it's plain comments you have to scan through massive piles of verbose >> Perl to find what you want. If it's pod you can just perldoc >> /path/to/module it and get a nice summary of the functions etc. >> >> If these are intended to become usable facilities for people to write tests >> with then I think it's important that the docs be reasonably accessible. > > Yes, I think adding POD here is a good idea. I considered doing it > myself back when I was messing with PostgresNode ...
OK, withdrawal from here. If there are patches to add that to the existing tests, I'll review them, and rebase what I have depending on what gets in first. Could a proper patch split be done please?
Just finished doing that. Thanks for taking a look at the first patch so quickly. I hope this one's better.
FWIW I think you were right that using pod for the actual test wasn't the best choice, I should've just used comments. I do think it's important for the modules to have structured docs.
I've removed the example suite in favour of adding a SYNOPSIS section to PostgresNode.pm and describing the rest in the README. It won't be necessary once your replication tests go in, they'll be a perfectly adequate example.
I also cut out the changes to the backup method; I'll send a pull to add to your proposed replication patch instead.