[PATCH] strbuf: describe the return value of strbuf_read_file()

[PATCH] strbuf: describe the return value of strbuf_read_file()

[Pranit Bauva]

Mentored-by: Lars Schneider <larsxschneider@gmail.com>
Mentored-by: Christian Couder <chriscool@tuxfamily.org>
Signed-off-by: Pranit Bauva <pranit.bauva@gmail.com>
---
It is easy to be misguided on the return value of the function
strbuf_read_file(). It does follow the pattern of other standard functions
for reading files but its better to explicitly specify it.

 strbuf.h | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/strbuf.h b/strbuf.h
index 7987405..4b487f7 100644
--- a/strbuf.h
+++ b/strbuf.h
@@ -377,6 +377,8 @@ extern ssize_t strbuf_read_once(struct strbuf *, int fd, size_t hint);
 /**
  * Read the contents of a file, specified by its path. The third argument
  * can be used to give a hint about the file size, to avoid reallocs.
+ * Return the number of bytes read or -1 if some error occurred while
+ * opening or reading the file.
  */
 extern ssize_t strbuf_read_file(struct strbuf *sb, const char *path, size_t hint);
 
-- 
2.8.4

Re: [PATCH] strbuf: describe the return value of strbuf_read_file()

[Junio C Hamano]

Pranit Bauva <pranit.bauva@gmail.com> writes:

> Mentored-by: Lars Schneider <larsxschneider@gmail.com>
> Mentored-by: Christian Couder <chriscool@tuxfamily.org>
> Signed-off-by: Pranit Bauva <pranit.bauva@gmail.com>
> ---
> It is easy to be misguided on the return value of the function
> strbuf_read_file(). It does follow the pattern of other standard functions
> for reading files but its better to explicitly specify it.

Good thing to do; I wonder if we want to explicitly say -1 or
leave it at "negative values are errors", though (my knee-jerk
reaction being "do not over-specify more than absolute minimum
to write callers correctly").

>
>  strbuf.h | 2 ++
>  1 file changed, 2 insertions(+)
>
> diff --git a/strbuf.h b/strbuf.h
> index 7987405..4b487f7 100644
> --- a/strbuf.h
> +++ b/strbuf.h
> @@ -377,6 +377,8 @@ extern ssize_t strbuf_read_once(struct strbuf *, int fd, size_t hint);
>  /**
>   * Read the contents of a file, specified by its path. The third argument
>   * can be used to give a hint about the file size, to avoid reallocs.
> + * Return the number of bytes read or -1 if some error occurred while
> + * opening or reading the file.
>   */
>  extern ssize_t strbuf_read_file(struct strbuf *sb, const char *path, size_t hint);

Re: [PATCH] strbuf: describe the return value of strbuf_read_file()

[Pranit Bauva]

Hey Junio,

On Tue, Jun 14, 2016 at 3:40 AM, Junio C Hamano <gitster@pobox.com> wrote:
>> It is easy to be misguided on the return value of the function
>> strbuf_read_file(). It does follow the pattern of other standard functions
>> for reading files but its better to explicitly specify it.
>
> Good thing to do; I wonder if we want to explicitly say -1 or
> leave it at "negative values are errors", though (my knee-jerk
> reaction being "do not over-specify more than absolute minimum
> to write callers correctly").

Sure I will re-roll with specifying about negative values as errors.

Regards,
Pranit Bauva