[vim/vim] quickfix documentation does not follow API documentation of getqflist(), getloclist() (#6786)

[latricewilgus]

The documentation (as of b3ea36c) of getqflist() and getloclist() states for its {what} parameter

If the optional {what} dictionary argument is supplied, then
returns only the items listed in {what} as a dictionary. The
following string items are supported in {what}:
[...]
Non-string items in {what} are ignored. To get the value of a
particular item, set it to zero.

That is it should be used like

echo getqflist({'title' : 0})
echo getloclist(0, {'title' : 0})

However, many example snippets in quickfix.txt (e.g. quickfix-title, quickfix-size, ...) use it like

echo getqflist({'title' : 1})  " with a 1
echo getloclist(0, {'title' : 1})  " with a 1

With the connotation of 1 being true/included and 0 being false/excluded, it is unclear what the correct usage is and what use cases are considered legal and which are undefined-behaviour.

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub, or unsubscribe.

[Yegappan Lakshmanan]

Hi,

On Mon, Aug 24, 2020 at 6:48 AM latricewilgus <vim-dev...@256bit.org> wrote:

The documentation (as of b3ea36c) of getqflist() and getloclist() states for its {what} parameter

If the optional {what} dictionary argument is supplied, then
returns only the items listed in {what} as a dictionary. The
following string items are supported in {what}:
[...]
Non-string items in {what} are ignored. To get the value of a
particular item, set it to zero.

That is it should be used like

echo getqflist({'title' : 0})
echo getloclist(0, {'title' : 0})

However, many example snippets in quickfix.txt (e.g. quickfix-title, quickfix-size, ...) use it like

echo getqflist({'title' : 1})  " with a 1
echo getloclist(0, {'title' : 1})  " with a 1

With the connotation of 1 being true/included and 0 being false/excluded, it is unclear what the correct usage is and what use cases are considered legal and which are undefined-behaviour.

For some items, the exact value doesn't matter. For the following items,

you can pass any numeric value: changedtick, context, items, qfbufnr,

size, title, winid and all.

The examples in the doc can be changed to use zero for the above items.

For the following items, the value determines what is returned.

id - quickfix list identifier. If zero or not specified, then the current

      list is used. Otherwise, the quickfix list with the specified

      identifier is used.

idx - quickfix entry index. If zero or not specified, then the

       current entry is used.

nr - quickfix list number in the quickfix stack. If zero or not specified,

      then the current list is used. This can be used instead of the

      quickfix list identifier to select a particular quickfix list.

- Yegappan

[vim-dev ML]

Hi,

On Mon, Aug 24, 2020 at 6:48 AM latricewilgus <vim-dev...@256bit.org>
wrote:

> The documentation (as of b3ea36c

> <https://github.com/vim/vim/commit/b3ea36c5bcb88b6a05a66347eedd461e9385103f>)

> of getqflist() and getloclist() states for its {what} parameter
>
> If the optional {what} dictionary argument is supplied, then
> returns only the items listed in {what} as a dictionary. The
> following string items are supported in {what}:
> [...]
> Non-string items in {what} are ignored. To get the value of a
> particular item, set it to zero.
>
> That is it should be used like
>
> echo getqflist({'title' : 0})
> echo getloclist(0, {'title' : 0})
>
> However, many example snippets in quickfix.txt (e.g. quickfix-title,
> quickfix-size, ...) use it like
>
> echo getqflist({'title' : 1}) " with a 1
> echo getloclist(0, {'title' : 1}) " with a 1
>
> With the connotation of 1 being true/included and 0 being false/excluded,
> it is unclear what the correct usage is and what use cases are considered
> legal and which are undefined-behaviour.
>
>

> For some items, the exact value doesn't matter. For the following items,
you can pass any numeric value: changedtick, context, items, qfbufnr,
size, title, winid and all.

The examples in the doc can be changed to use zero for the above items.

For the following items, the value determines what is returned.

id - quickfix list identifier. If zero or not specified, then the current
list is used. Otherwise, the quickfix list with the specified
identifier is used.
idx - quickfix entry index. If zero or not specified, then the
current entry is used.
nr - quickfix list number in the quickfix stack. If zero or not specified,
then the current list is used. This can be used instead of the
quickfix list identifier to select a particular quickfix list.

- Yegappan

[Christian Brabandt]

I am closing this, unless somebody wants to suggest a documentation change, in which case please create a new issue or PR with specific changes. Thanks.

—
You are receiving this because you commented.

[Christian Brabandt]

Closed #6786.

—
You are receiving this because you commented.