Should .dispose() be a trapdoor function?

[xobs]

As part of lifecycle management, xterm.dispose() exists to dispose of a terminal object. The documentation states that this function:

    /*
     * Disposes of the terminal, detaching it from the DOM and removing any
     * active listeners.
     */
    dispose(): void;

However, as part of this process, it also overwrites the .write() call, making the terminal no longer usable.

It seems as though the opposite would be open():

    /**
     * Opens the terminal within an element.
     * @param parent The element to create the terminal within. This element
     * must be visible (have dimensions) when `open` is called as several DOM-
     * based measurements need to be performed when this function is called.
     */
    open(parent: HTMLElement): void;

Should this be the case? Should .open() reinstate the .write() call? Or should the documentation be updated to reflect the fact that this is an error, and perhaps a warning be added to .write() or .open() to indicate the user is using a terminal that has been disposed of?

This is an extension of the discussion from #3910

[Tyriar]

When you dispose the object it's not meant to be used again, you may be able to but thing will inevitably go wrong. For clear the write call, that's just always been like that since the project was created. We wouldn't normally clear a method like that though.

For robert-harbison/xterm-for-react#13 it definitely shouldn't be using dispose, instead I think the best way now is to remove the container element (that was opened) from the DOM, and then when it's added, call open again.

[xobs]

Thanks for the explanation -- it seems like dispose() is effectively a destructor. Perhaps that terminology is common in Javascript but I'm just not familiar with it.

Would it make sense to add a sentence to the dispose() API description stating that the object should never be used after it is disposed of?

[Tyriar]

It's used throughout vscode and xterm.js but yes it's never made super clear. I think it's a good idea to change the description of Terminal.dispose to make it clear👍