bug#69666: [PATCH] (vtable-update-object): Make old-object argument optional

[Eli Zaretskii]

> Date: Fri, 8 Mar 2024 23:51:33 -0600
> From: Adam Porter <adam@alphapapa.net>
> 
> Please see the attached patch which makes `vtable-update-object' easier 
> to use in the common case of updating an existing object's 
> representation in a table (rather than replacing it with another object).

Thanks, I have some minor comments below.

> Subject: [PATCH] (vtable-update-object): Make old-object argument optional

Since this changes the API of a public function, we need to call this
out in NEWS.

> +@defun vtable-update-object table object &optional old-object
> +Change @var{old-object} into @var{object} in @var{table}; or, without
> +@var{old-object}, update existing @var{object} in @var{table}.  This
> +also updates the displayed table.

This is backwards: the documentation should first say what happens if
the function is called with just 2 arguments, and then what happens if
the 3rd one is supplied.  Like this:

  Update @var{object} in @var{table} and redisplay @var{table}.
  Optional argument @var{old-object}, if non-@code{nil}, means to
  change @var{old-object} into @var{object}.

> +(defun vtable-update-object (table object &optional old-object)
> +  "Replace OLD-OBJECT in TABLE with OBJECT.
> +Without OLD-OBJECT, just update existing OBJECT in TABLE."

Same here.