[vim/vim] doc: Clarify when list is ignored in setqflist (#5741)

[David Briscoe]

This is a very minor improvement, but I think it might have resolved my confusion in the discussion of #5735.

I didn't realize that when {what} is included that {list} is completely ignored. I also missed that it says list is ignored in the section on {what}.

Also added newlines around the {what} argument table to match style of {list}
argument table.

---

You can view, comment on, or merge this pull request online at:

  https://github.com/vim/vim/pull/5741

Commit Summary

• help: Clarify when list is ignored in setqflist

File Changes

• M runtime/doc/eval.txt (10)

Patch Links:

• https://github.com/vim/vim/pull/5741.patch
• https://github.com/vim/vim/pull/5741.diff

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

[Codecov]

Codecov Report

Merging #5741 into master will decrease coverage by 0.02%.
The diff coverage is n/a.

@@            Coverage Diff             @@

##           master    #5741      +/-   ##

==========================================

- Coverage   84.21%   84.18%   -0.03%     

==========================================

  Files         138      138              

  Lines      152442   152442              

==========================================

- Hits       128372   128328      -44     

- Misses      24070    24114      +44

Impacted Files	Coverage Δ
src/ui.c	71.29% <0%> (-1.2%)	⬇️
src/gui.c	63.58% <0%> (-0.67%)	⬇️
src/gui_gtk_x11.c	58.06% <0%> (-0.45%)	⬇️
src/netbeans.c	27.23% <0%> (-0.3%)	⬇️
src/sign.c	94.5% <0%> (-0.27%)	⬇️
src/os_unix.c	63.51% <0%> (-0.23%)	⬇️
src/terminal.c	82.57% <0%> (-0.04%)	⬇️
src/ops.c	89.69% <0%> (+0.04%)	⬆️
src/message.c	88.55% <0%> (+0.04%)	⬆️
src/drawscreen.c	83.71% <0%> (+0.15%)	⬆️
... and 1 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 8eab731...03b2efc. Read the comment docs.

[Bram Moolenaar]

Closed #5741.

[Bram Moolenaar]

Yeah, it's strange that the first argument is ignored. Should have made a separate function.
I'll move the remark about using {what} to the start, I think that works better than rephrasing the line about {list}.

[Yegappan Lakshmanan]

Hi Bram,

On Mon, Mar 9, 2020 at 3:19 AM Bram Moolenaar <vim-dev...@256bit.org> wrote:

Yeah, it's strange that the first argument is ignored. Should have made a separate function.
I'll move the remark about using {what} to the start, I think that works better than rephrasing the line about {list}.

What do you think about deprecating the first argument to setqflist()

by hiding it and modifying setqflist() to also accept the {what} dict

as the first argument? The current syntax will be supported for

backward compatibility, but the documentation will describe only

the syntax with the {dict} argument. To set items in a quickfix list,

the 'items' key in the {dict} argument can be used.

Thanks,

Yegappan

[vim-dev ML]

[Bram Moolenaar]

I think that is going in the wrong direction. We have started to do
more type checking, especially in the :def functions. It is then a bit
strange to have an argument that can be a list or a dict. I know we
already do this in a few places, but In my opinion we should not add
more.

It's probably better to use another function. setqfdict() perhaps?
Strictly speaking it would be setqflistbydict(), but that is much too
long.

--
hundred-and-one symptoms of being an internet addict:
199. You read this entire list of symptoms, looking for something
that doesn't describe you.

/// Bram Moolenaar -- Br...@Moolenaar.net -- http://www.Moolenaar.net \\\
/// sponsor Vim, vote for features -- http://www.Vim.org/sponsor/ \\\
\\\ an exciting new programming language -- http://www.Zimbu.org ///
\\\ help me help AIDS victims -- http://ICCF-Holland.org ///

[vim-dev ML]

[Yegappan Lakshmanan]

Hi Bram,

On Mon, Mar 9, 2020 at 10:24 AM Bram Moolenaar <Br...@moolenaar.net> wrote:
>
>
> Yegappan Lakshmanan wrote:
>
> > On Mon, Mar 9, 2020 at 3:19 AM Bram Moolenaar <vim-dev...@256bit.org>
> > wrote:
> >
> > > Yeah, it's strange that the first argument is ignored. Should have made a
> > > separate function.
> > > I'll move the remark about using {what} to the start, I think that works
> > > better than rephrasing the line about {list}.
> >
> > What do you think about deprecating the first argument to setqflist()
> > by hiding it and modifying setqflist() to also accept the {what} dict
> > as the first argument? The current syntax will be supported for
> > backward compatibility, but the documentation will describe only
> > the syntax with the {dict} argument. To set items in a quickfix list,
> > the 'items' key in the {dict} argument can be used.
>
> I think that is going in the wrong direction. We have started to do
> more type checking, especially in the :def functions. It is then a bit
> strange to have an argument that can be a list or a dict. I know we
> already do this in a few places, but In my opinion we should not add
> more.
>
> It's probably better to use another function. setqfdict() perhaps?
> Strictly speaking it would be setqflistbydict(), but that is much too
> long.
>

We can call the function setqfprop() for setting the quickfix list
properties? I created a patch for this a few years ago but didn't
send it out. If this approach is acceptable, I will create a PR.

Thanks,
Yegappan

[vim-dev ML]

[Bram Moolenaar]

Yegappan Lakshmanan wrote:

> > > On Mon, Mar 9, 2020 at 3:19 AM Bram Moolenaar <vim-dev...@256bit.org>
> > > wrote:
> > >
> > > > Yeah, it's strange that the first argument is ignored. Should have made a
> > > > separate function.
> > > > I'll move the remark about using {what} to the start, I think that works
> > > > better than rephrasing the line about {list}.
> > >
> > > What do you think about deprecating the first argument to setqflist()
> > > by hiding it and modifying setqflist() to also accept the {what} dict
> > > as the first argument? The current syntax will be supported for
> > > backward compatibility, but the documentation will describe only
> > > the syntax with the {dict} argument. To set items in a quickfix list,
> > > the 'items' key in the {dict} argument can be used.
> >
> > I think that is going in the wrong direction. We have started to do
> > more type checking, especially in the :def functions. It is then a bit
> > strange to have an argument that can be a list or a dict. I know we
> > already do this in a few places, but In my opinion we should not add
> > more.
> >
> > It's probably better to use another function. setqfdict() perhaps?
> > Strictly speaking it would be setqflistbydict(), but that is much too
> > long.
> >
>
> We can call the function setqfprop() for setting the quickfix list
> properties? I created a patch for this a few years ago but didn't
> send it out. If this approach is acceptable, I will create a PR.

That sounds good to me.

--
hundred-and-one symptoms of being an internet addict:

202. You're amazed to find out Spam is a food.