The pg_basebackup page says that the --waldir parameter "Specifies the location for the write-ahead log directory. waldir must be an absolute path. The write-ahead log directory can only be specified when the backup is in plain mode." But it says nothing at all about what it is actually used for.
You may think it is obvious. And I thought I could guess - it would be the directory containing the WAL files for the database, right?
It's not the directory "of" the write-ahead log directory (i.e., existing) but the directory "for" the write-ahead log directory (i.e. in the backup). All information about the database being backed up can be gleaned from the connection the pg_basebackup makes to the server.
Which makes me realise I must have been completely wrong and I have no idea what it for.
I believe its purpose is to allow the user to specify a different directory for the necessary restoration WAL files to be placed in compared to the working WAL directory that will be created under the pgdata directory.
As with most things there is always room for improvement. In this case, though, I'm not seeing anything wrong with the direct wording provided. The behavior of the program, and general context, means that the directory must be one that is being created during the backup and WAL copied into it. And the error message means that in the rare case that the users mis-interprets it they will be told. And as in this case the mailing lists are responsive to clearing up individual confusion should the need arise.
Adding here, and in other places, explicit documentation that "this specifies a location in the backup" just makes the documentation more verbose. Maybe in this case not enough to reject a proposed patch but enough so that I at least don't have a desire to write one.
