Re: Rotten parts of src/backend/replication/README

On Sat, May 02, 2020 at 04:54:32PM +0530, Amit Kapila wrote:
> I think in README we can have a general description of the module and
> maybe at the broad level how different APIs can help to achieve the
> required functionality and then for API description we can refer to
> .h/.c.  The detailed description of APIs should be where those APIs
> are defined.  The header file can contain some generic description.
> The detailed description I am referring to is below in the README:
> "Retrieve any message available without blocking through the
> connection.  If a message was successfully read, returns its length.
> If the connection is closed, returns -1.  Otherwise returns 0 to
> indicate that no data is available, and sets *wait_fd to a socket
> descriptor which can be waited on before trying again.  On success, a
> pointer to the message payload is stored in *buffer. The returned
> buffer is valid until the next call to walrcv_* functions, and the
> caller should not attempt to free it."
> 
> I think having such a description near the actual definition helps in
> keeping it updated whenever we change the function.

Yeah.  The years have visibly proved that the README had updates when
it came to the general descriptions of the libpqwalreceiver interface,
but that we had better consolidate the header to give some
documentation to whoever plays with this interface.  Attached is a
patch to address all that, where I simplified the README and added
some description to all the callbacks.  Thoughts are welcome.  I'll
add that to the next CF.  Now I don't see any actual problems in
getting that on HEAD before v13 forks.  But let's gather more opinions
first.
--
Michael