When having multiple overloads for functions,
most of the time there is this overlaping of the previous and the current signature.

I experimented resizing the popup with a couple of different values for max_width (700, ..., 500, 400) and concluded that when I set it to 400 the popup doesn't overlap that much.

Did other people noticed this as well?
The overlapping looks like a bug with how we set size constraints or how sublime solves for them when popup content is updated.
If we re-create the popup instead of updating it with update_popup does it blink a lot?
This is a bug, just don't know if it is related directly to sublime or mdpopups.
I found a workaround for this, which is not a nice one, but it works:
def _update_popup(self) -> None:
content = self._build_popup_content()
mdpopups.update_popup(self.view,
content,
css=popup_css,
md=True,
wrapper_class=popup_class)
mdpopups.update_popup(self.view,
content,
css=popup_css,
md=True,
wrapper_class=popup_class)
Calling 2x update_popup updates the popup with no overlapping.

FWIW, I am on Linux,
Does this happen on other OS-es?
ping @facelessuser maybe.
This sounds like a Sublime rendering issue to me. Mdpopups calls Sublime's update when you call mdpopup's update.
Anything else would be a hack as @predragnikolic is doing. Sublime should be the one to redraw the dialog proper. We shouldn't have to update multiple times or clear the popup and then create a new one.
@facelessuser, thanks for the clarification.
Yes apparently this is a sublime text bug. Here is an example of using the sublime view.update_popup function.

I imagine it is specific to certain distros due to different versions of GTK or whatever it uses. I'm pretty sure it doesn't manifest on Windows or Mac, but maybe 🤷♂️ . It's probably difficult to test every variant, so I imagine these things sneak in.
To be honest this was one of the first problem I noticed when I tried LSP :D that was late 2017. So this exist for a long time.
Ether way, issues are here to be resolved. I will make a issue on sublime/core. :)
It was fixed! :)
Most helpful comment
It was fixed! :)