[FFmpeg-devel] [PATCH 2/8] lavu: new AVWriter API

[Rodney Baker]

I'm not normally a reviewer, but I noticed a few minor grammatical things that 
stood out - hope this is OK. 

Regards,
Rodney.

On Friday, 28 April 2023 7:25:02 PM ACST Nicolas George wrote:
> Signed-off-by: Nicolas George <george at nsup.org>
> ---
>  doc/avwriter_intro.md | 186 ++++++++++++++++
>  libavutil/Makefile    |   2 +-
>  libavutil/writer.c    | 458 +++++++++++++++++++++++++++++++++++++++
>  libavutil/writer.h    | 488 ++++++++++++++++++++++++++++++++++++++++++
>  4 files changed, 1133 insertions(+), 1 deletion(-)
>  create mode 100644 doc/avwriter_intro.md
>  create mode 100644 libavutil/writer.c
>  create mode 100644 libavutil/writer.h
> 
> diff --git a/doc/avwriter_intro.md b/doc/avwriter_intro.md
> new file mode 100644
> index 0000000000..0e092246a2
> --- /dev/null
> +++ b/doc/avwriter_intro.md
> @@ -0,0 +1,186 @@
> +# Quick start guide for AVWriter
> +
> +AVWriter is an API to unify functions returning strings and to make
> building +strings from parts easier. In this document, you will find an
> introduction +on how to *use* AVWriter, mostly in the form of code snippets
> compating +mainstream C solutions with their AVWriter counterpart.

Nit - s/compating/comparing/

[...]
> +
> +**Note:** AVWriter is 8-bit clean, the strings it manipulates can be

Use a hyphen or a semicolon rather than a comma after "clean". 

> buffers +of binary data. The documentation is mostly written uing the
> vocabulary of +strings for simplicity.
> +
> +In mainstream C, a function that needs to return a string usually have two
> +options: either they accept pointer to a buffer that they fill or they
> +allocate the buffer themselves and return it. Both these options have
> +drawbacks, which one is best depends on the circumstances of the caller.

Semicolon instead of comma after "drawbacks".

> +
> +AVWriter lets the caller choose the option best suited to the
> circumstances, +among a small variety of built-in options or custom

Drop comma after "circumstances". 

> implementations, +including on-the-fly compression or escaping and direct
> writing to a file. +The first built-in implementation, where the strings is
> stored in a +dynamically-allocated buffer, includes the optimization that
> small strings +are kept on the stack.
> +
> +AVWriter also makes the work of the called function easier by providing
> +convenient functions to append to the string that completely wrap error
> +checks. Note that it only works for strings created as streams; functions
> +that need random access to the string already built still need to manage
> +their own buffers; some AVWriter implementations can still help for that.

Full stop after "buffers" (instead of semicolon - you've already used one 
previously in the same sentence). 

[...]

-- 
==================================================================================================================
Rodney Baker
rodney.baker at iinet.net.au
==================================================================================================================