docs: Improve clarity in documentation for Frame

[kdheepak]

The documentation currently says This allows for widgets to be drawn in any order. which I believe is incorrect.

I removed that line and tweaked the remaining text for more clarity.

[codecov]

Codecov Report

Merging #545 (119ebc3) into main (11076d0) will not change coverage.
Report is 2 commits behind head on main.
The diff coverage is n/a.

@@           Coverage Diff           @@
##             main     #545   +/-   ##
=======================================
  Coverage   89.65%   89.65%           
=======================================
  Files          41       41           
  Lines       11437    11437           
=======================================
  Hits        10254    10254           
  Misses       1183     1183           

Files	Coverage Δ
src/terminal.rs	58.46% <ø> (ø)

[joshka]

Is there a way to rephrase this without "changes drawn"? I don't get from that wording that the entire frame should be drawn rather than the full frame needs to be refreshed.

[kdheepak]

How about something like this?

/// The `Terminal` struct maintains two buffers: the current and the previous.
/// When the widgets are drawn, the changes are accumulated in the current buffer.
/// At the end of each draw pass, the two buffers are compared, and only the changes
/// between these buffers are written to the terminal, avoiding any redundant operations.
/// After flushing these changes, the buffers are swapped to prepare for the next draw cycle.

[joshka]

How about something like this?

/// The `Terminal` struct maintains two buffers: the current and the previous.
/// When the widgets are drawn, the changes are accumulated in the current buffer.
/// At the end of each draw pass, the two buffers are compared, and only the changes
/// between these buffers are written to the terminal, avoiding any redundant operations.
/// After flushing these changes, the buffers are swapped to prepare for the next draw cycle.

LGTM

[kdheepak]

Looking at the code again. This change is for the Frame struct, but the comment I shared above is better documentation for the Terminal struct.

I'm pushing another change that rephrases the comment for the Frame struct and updating the Terminal struct's docstring with the text above. Let me know what you think?