On Sat 02 Feb 2019 at 10:33, Eli Zaretskii <eliz@gnu.org> wrote:

> This should mention the bug number.

Thanks, done

>> +@defun tabulated-list-delete-entry
>> +This function deletes the entry at point.
>> +
>> +It returns a list @code{(id cols)} where @var{id} is the ID of the
>                                      ^
> A comma is missing there.

Thanks, added.

>> +delete entry and @var{cols} is a vector of its column descriptors.
>                ^
> And here.

I don't think a comma is needed here. It's a list of two entries, not
three, so no comma, right?

> Also, the "id" and "cols" inside the list should also have the @var
> markup.

Thanks, added like @code{(@var{id} @var{cols})}

>> +It moves point to the beginning of the deleted entry.
>
> The last sentence is confusing: if the entry is deleted, how can we
> move to its beginning?

Changed to "It moves point to the beginning of the current line."

>> +@defun tabulated-list-header-overlay-p &optional POS
>> +This @code{defsubst} returns non-nil if there is a fake header at
>> +@var{pos}.
>
> We should explain, in a single sentence if possible, what is a "fake
> header".  It is never explained in this section.

Added as "A fake header is used if @code{tabulated-list-use-header-line} is @code{nil} to put the column names at the beginning of the buffer."

>> +@defun tabulated-list-put-tag tag &optional advance
>> +This function puts @var{tag} in the padding area of the current line.
>
> And this should explain what is the padding area, for the same reason.

Added as "The padding area can be empty space at the beginning of the line, the width of which is governed by @code{tabulated-list-padding}."

>> +@var{tag} should be a string, with a length less than or equal to
>> +@code{tabulated-list-padding}.
>
> Every variable mentioned in the manual should be indexed.  So please
> add
>
>  @vindex tabulated-list-padding
>
> before the @defun.

Done (also for tabulated-list-use-header-line)

>> +If @var{change-entry-data} is non-nil, this function modifies the
>> +underlying entry data by setting the appropriate slot of the vector
>> +originally used to print this entry.  If @code{tabulated-list-entries}
>> +has a list value, this is the vector stored within it.
>
> This paragraph is confusing, I cannot understand what that argument
> does just by reading the above text.  (The doc string says the same,
> so it's of no help.)  The confusing parts are "appropriate slot" and
> "originally used to print".  The code simply modifies a component of
> the vector returned by tabulated-list-get-entry, so I wonder why the
> description needs to be that complicated.

Changed to this, which is hopefully clearer:

If @var{change-entry-data} is non-nil, this function modifies the
underlying data (usually the column descriptor in the list
@code{tabulated-list-entries}) by setting the column descriptor of the
vector to @code{desc}.

Thanks,
Alex