Refine company-auto-update-doc behavior

[vemv]

Hi,

I'm much enjoying setting company-auto-update-doc in advance to t. It makes much sense for specific modes (e.g. clojure-mode) where I know that the vast majority of times there will be useful documentation that will better inform multiple-choice completions.

There are however, two exceptions:

• If there's exactly one completion available, completion will be performed (which is correct and desirable) but the documentation will still be shown
  • I find this makes little sense: generally documentation helps one choose. Without multiple candidates, there's nothing to choose
  • Otherwise I find that showing documentation interrupts user flow - single-candidate completions are most often tokens that are already typed in for the most part, and that the user is already familiar with.
  • One always can show equivalent documentation later, with some other command.
• If there's no documentation available, and no buffer created by :company-doc-buffer currently exists (or is visible), then showing a *company-documentation* buffer saying No documentation available is not useful
  • Example: there are 2 candidates, none of those has documentation, then at no point a :company-doc-buffer buffer should be rendered - it adds no info and is a distraction.
  • It is however, useful, if there are 2 candidates, the former with documentation and the latter not, that the latter triggers a *company-documentation* buffer saying No documentation available. That way I won't be mislead to believe that the previous documentation buffer applies to the current candidate.

WDYT?

Thanks - V

[dgutov]

Regarding item 2, I think that's the design that @nemethf had in mind (let's wait for him to comment). And I think it has its benefit: the window configuration doesn't change, so there's never any "jumping".

If there's exactly one completion available, completion will be performed (which is correct and desirable) but the documentation will still be shown

Do you mean the case when you are typing and are still yet to press RET (so you see the inline completion from the preview frontend), or when you M-x company-complete-common, and the completion finishes right away? The latter case it's a part of the bug you've filed (and my proposed patch seems to fix it). The former is arguably useful behavior (one might want to read the doc before performing completion: it's not always for choosing).

[dgutov]

Which is to say that both choices seem deliberate, but we could always add more user options, of course.

[vemv]

Thanks much for the quick response!

Yes, of course there's a big chance that most things follow a deliberate design.

What I meant is:

• If company-auto-update-doc is set to t beforehand;
• And the symbol foobarbaz has no documentation;
• and I type foobar;
  • if I run M-x company-dabbrev, the documentation buffer will be rendered
  • if I run M-x company-complete, the documentation buffer will be not rendered
  • (completion will be performed for both cases)

...this issue might be specific to company-dabbrev - I just discovered that nuance now.

[dgutov]

company-dabbrev is not unique in not supporting documentation. It's not a required functionality anyway.

if I run M-x company-dabbrev, the documentation buffer will be rendered

It seems to be shown here anyway (with the current code). Saying "foobarbaz: No documentation available".

[dgutov]

I've pushed a tentative change where the buffer is hidden when the current completion has no doc. Branch company-auto-update-doc-tweaks, commit f3ee625. The upside and downside both seem expected.

@vemv @nemethf Opinions?

[vemv]

I checked out both commits in company-auto-update-doc-tweaks and they make sense to me.

[nemethf]

@nemethf Opinions?

As you said this version shows the "jumping" effect. For example:

// documentation
void foo111() {};
void foo222() {};
// documentation
void foo333() {};
void foo444() {};

void main() {
  foo
}

With "Emacs 30.0.50" and "clangd version 14.0.6" if I company-complete foo in main() and press C-n many times, then the original single window is split into two then the new window is deleted and the cycle repeats.

However, the code is much simpler and personally I can live with this effect. (Although I think this is a bit ugly.)

Thanks

[dgutov]

then the original single window is split into two then the new window is deleted and the cycle repeats.

And otherwise (currently) we display a full empty window with just one line ("No documentation available").

I don't mind adding a new option to control this, if there is interest, but it would be ideal to settle on some optimal behavior. For example, we could avoid showing the doc window until some completion actually has a doc. And then we would keep the window around no matter what until either completion is inserted, or company-auto-update-doc is toggled off.

[dgutov]

Anyway, like with the other issue (new command which makes the doc stay around), there is not much urgency in making this choice now. If both of you are okay with the proposed intermediate change, any tweaks can come later.

[vemv]

I'll be checking out the new MELPA snapshots, thanks.

[vemv]

From my testing, both of the issues described in my OP are now solved.

[dgutov]

All right, then I'll close the discussion. @nemethf You're welcome to open new issue if you want a user option to have the other behavior (it's very easy to add).