[PATCH] pkt-line.h: move comment closer to the associated code

[PATCH] pkt-line.h: move comment closer to the associated code

[Matheus Tavares]

ec9a37d ("pkt-line.[ch]: remove unused packet_read_line_buf()",
2021-10-14) removed the "src_buffer" and "src_len" parameters from
packet_read(), only leaving them at packet_read_with_status(). Let's
also update the function documentation by moving the comment about these
parameters from the former to the latter.

Signed-off-by: Matheus Tavares <matheus.bernardino@usp.br>
---
 pkt-line.h | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/pkt-line.h b/pkt-line.h
index 6d2a63db23..1f623de60a 100644
--- a/pkt-line.h
+++ b/pkt-line.h
@@ -49,14 +49,6 @@ void packet_fflush(FILE *f);
  * Read a packetized line into the buffer, which must be at least size bytes
  * long. The return value specifies the number of bytes read into the buffer.
  *
- * If src_buffer and *src_buffer are not NULL, it should point to a buffer
- * containing the packet data to parse, of at least *src_len bytes.  After the
- * function returns, src_buf will be incremented and src_len decremented by the
- * number of bytes consumed.
- *
- * If src_buffer (or *src_buffer) is NULL, then data is read from the
- * descriptor "fd".
- *
  * If options does not contain PACKET_READ_GENTLE_ON_EOF, we will die under any
  * of the following conditions:
  *
@@ -104,6 +96,14 @@ int packet_length(const char lenbuf_hex[4]);
  * returns an 'enum packet_read_status' which indicates the status of the read.
  * The number of bytes read will be assigned to *pktlen if the status of the
  * read was 'PACKET_READ_NORMAL'.
+ *
+ * If src_buffer and *src_buffer are not NULL, it should point to a buffer
+ * containing the packet data to parse, of at least *src_len bytes.  After the
+ * function returns, src_buf will be incremented and src_len decremented by the
+ * number of bytes consumed.
+ *
+ * If src_buffer (or *src_buffer) is NULL, then data is read from the
+ * descriptor "fd".
  */
 enum packet_read_status {
 	PACKET_READ_EOF,
-- 
2.37.1

Re: [PATCH] pkt-line.h: move comment closer to the associated code

[Ævar Arnfjörð Bjarmason]

On Fri, Jul 22 2022, Matheus Tavares wrote:

> ec9a37d ("pkt-line.[ch]: remove unused packet_read_line_buf()",

Nit: "log --pretty=reference" for me emits this length of SHA-1 on a
fresh clone:

	ec9a37d69b (pkt-line.[ch]: remove unused packet_read_line_buf(), 2021-10-14)

In this case ec9a3 is non-colliding, but you might want to adjust
whatever your local alias is to use our default hash length instead of a
presumably hardcoded length of 7 ;)

No need to re-roll for that...

> 2021-10-14) removed the "src_buffer" and "src_len" parameters from
> packet_read(), only leaving them at packet_read_with_status(). Let's
> also update the function documentation by moving the comment about these
> parameters from the former to the latter.
>
> Signed-off-by: Matheus Tavares <matheus.bernardino@usp.br>
> ---
>  pkt-line.h | 16 ++++++++--------
>  1 file changed, 8 insertions(+), 8 deletions(-)
>
> diff --git a/pkt-line.h b/pkt-line.h
> index 6d2a63db23..1f623de60a 100644
> --- a/pkt-line.h
> +++ b/pkt-line.h
> @@ -49,14 +49,6 @@ void packet_fflush(FILE *f);
>   * Read a packetized line into the buffer, which must be at least size bytes
>   * long. The return value specifies the number of bytes read into the buffer.
>   *
> - * If src_buffer and *src_buffer are not NULL, it should point to a buffer
> - * containing the packet data to parse, of at least *src_len bytes.  After the
> - * function returns, src_buf will be incremented and src_len decremented by the
> - * number of bytes consumed.
> - *
> - * If src_buffer (or *src_buffer) is NULL, then data is read from the
> - * descriptor "fd".
> - *
>   * If options does not contain PACKET_READ_GENTLE_ON_EOF, we will die under any
>   * of the following conditions:
>   *
> @@ -104,6 +96,14 @@ int packet_length(const char lenbuf_hex[4]);
>   * returns an 'enum packet_read_status' which indicates the status of the read.
>   * The number of bytes read will be assigned to *pktlen if the status of the
>   * read was 'PACKET_READ_NORMAL'.
> + *
> + * If src_buffer and *src_buffer are not NULL, it should point to a buffer
> + * containing the packet data to parse, of at least *src_len bytes.  After the
> + * function returns, src_buf will be incremented and src_len decremented by the
> + * number of bytes consumed.
> + *
> + * If src_buffer (or *src_buffer) is NULL, then data is read from the
> + * descriptor "fd".
>   */
>  enum packet_read_status {
>  	PACKET_READ_EOF,

This change looks good to me, thanks for catching this & cleaning up
after my change.

Re: [PATCH] pkt-line.h: move comment closer to the associated code

[Matheus Tavares]

On Fri, Jul 22, 2022 at 8:25 AM Ævar Arnfjörð Bjarmason
<avarab@gmail.com> wrote:
>
>
> On Fri, Jul 22 2022, Matheus Tavares wrote:
>
> > ec9a37d ("pkt-line.[ch]: remove unused packet_read_line_buf()",
>
> Nit: "log --pretty=reference" for me emits this length of SHA-1 on a
> fresh clone:
>
>         ec9a37d69b (pkt-line.[ch]: remove unused packet_read_line_buf(), 2021-10-14)
>
> In this case ec9a3 is non-colliding, but you might want to adjust
> whatever your local alias is to use our default hash length instead of a
> presumably hardcoded length of 7 ;)

Thanks, will do :)