Why do we need to call this.adjustDocsPosition again here? None of the constants declared above this if condition gets changed by this.preferDocPositionTop = true

I will double check tomorrow when I have a moment, but if I remember correctly I believe it's because at this point it has now flipped back to the bottom so I am forcing it to rerender back to the top. I will verify though.

To give context and explain a bit better I will outline the original behavior, without the adjustDocsPosition, and with the adjustDocsPosition

Original behavior
When opening intellisense documentation. Moving through each option with the arrow keys the documentation will swap up and down depending on the space creating the jarring experience.

Without adjustDocsPosition
When opening intellisense documentation. The first time the docs position swaps from the bottom to the top it will trigger the preferDocPositionTop flag so subsequent moves through the documentation suggestions will stick to the top after the first one triggered goes to the bottom.

With adjustDocsPosition
When opening intellisense documentation. The first time the docs position adjusts it will trigger the preferDocPositionTop flag but prevent any noticeable difference that it had swapped at all and just look like it was at the top the whole time.

This is because of this line right above which creates a side effect causing the documentation position to re-evaluate where things should go.

const cursorCoords = this.editor.getScrolledVisiblePosition(this.editor.getPosition());

Let me know if I can answer this question more clearly or differently to help. Thank you for looking and commenting!

In that case, why not exit after calling adjustDocsPosition?

ie. Replace the this.adjustDocsPosition() here with

this.docsPositionPreviousWidgetY = widgetY;
this.adjustDocsPosition();
return;

Yes makes sense :) I'll update and rebase.

Shouldnt we reset this.docsPositionPreviousWidgetY here as well?

Updated :)