`TextChanged` event semantics are confusing

[BDisp]

Summary

TextDocument.TextChanged is misleading and collides with the IDocument.TextChanged semantics.

Description

TextDocument exposes a public event EventHandler TextChanged, but the IDocument interface also defines event EventHandler<TextChangeEventArgs> TextChanged.

In TextDocument:

• public event EventHandler TextChanged is raised by FireChangeEvents() after EndUpdate() / change group completion.
• IDocument.TextChanged is implemented explicitly and raised by DoReplace() immediately after each individual document change, with TextChangeEventArgs.

That means:

• TextDocument doc = new TextDocument(); doc.TextChanged += ... receives a change-completed notification without any change details.
• ((IDocument)doc).TextChanged += ... receives the actual per-change event with TextChangeEventArgs.

This is very likely to confuse consumers and causes surprising behavior.

Expected behavior

• TextDocument.TextChanged should either match the IDocument.TextChanged semantics/signature,
• or the public event should be renamed to something like ChangeCompleted / UpdateFinished.

The explicit interface implementation should remain consistent and clear.

Suggested fix

• Rename or clarify the public TextChanged event in TextDocument so it does not collide with IDocument.TextChanged.
• Prefer public event EventHandler ChangeCompleted; and keep IDocument.ChangeCompleted aliasing it.
• Preserve IDocument.TextChanged as the per-change event with TextChangeEventArgs.

Location

src/Terminal.Gui.Editor/Document/TextDocument.cs (TextChanged declaration and FireChangeEvents() / DoReplace() behavior)

[tig]

After digging into this, I think the issue is valid in the sense that the naming is easy to misread, but I don't think we should change the API surface unless we find a stronger reason.

These event names and semantics come from AvaloniaEdit:

• TextDocument.Changed fires after each individual document mutation and carries DocumentChangeEventArgs.
• IDocument.TextChanged also represents each individual mutation, but through the interface and with TextChangeEventArgs.
• TextDocument.TextChanged is different: it fires after a change group completes, i.e. after EndUpdate(), and may represent one or more mutations.
• IDocument.ChangeCompleted aliases that grouped-completion notification.

So the confusing part is real, but it is inherited API behavior rather than an accidental mismatch introduced here.

My preferred surgical fix is documentation-only: update the XML docs around TextDocument.TextChanged, TextDocument.Changed, and the BeginUpdate/EndUpdate event-order remarks to explicitly say that public TextDocument.TextChanged is a change-group-completed notification, not the per-edit detailed event. We can also add tests that lock the current semantics: multiple edits inside one update group should raise Changed / IDocument.TextChanged per edit, and TextDocument.TextChanged / IDocument.ChangeCompleted once at group completion.

That keeps compatibility and AvaloniaEdit mergeability while making the API behavior much clearer.

[BDisp]

Understood. My concern was in the cases where some view rely on Editor text changes to perform some action, which I didn't found any events for that. But I'll take a look better.

[tig]

Doesn't TextDocument.Changed work for that?

[BDisp]

I didn't saw that event before. I'll check it later. Thanks.

[tig]

Ok, once you figure that out and are ok, let me know. I think you can close the PR you opened?

I'll open another PR to make the API docs better.

[BDisp]

Agree.

[tig]

the docs are confusing. Keeping this open so I can submit a pr for it.

[BDisp]

Anyway I'll investigate why the test failed on macos only.