docs: Update section on rendering 📚

[kdheepak]

No description provided.

[github-actions]

PR Preview Action v1.4.4
Preview removed because the pull request was closed.
2023-10-07 18:07 UTC

[joshka]

I'm very much a top down (or outside-in) person when it comes to something like this. What do you think about flipping this article fully upside down (widget->frame->buffer->cell) (and then talking about the frame/terminal/backend last).

Why? Because I think it tells the person why they need to know the details before showing them that detail rather than the reverse.

[kdheepak]

I removed the following content because I didn't know if it fit well in the description:

For example, when you create an instance of a `Paragraph` struct, any content you pass in is
converted to a [`Text`] struct.

```rust
pub struct Paragraph<'a> {
    /// The text to display
    text: Text<'a>,
    // --snip--
}
```

A `Text` struct consists of [`Line`]s which consists of [`Span`]s.

```rust
pub struct Text<'a> {
    pub lines: Vec<Line<'a>>,
}

pub struct Line<'a> {
    pub spans: Vec<Span<'a>>,
    pub alignment: Option<Alignment>,
}

pub struct Span<'a> {
    /// The content of the span as a Clone-on-write string.
    pub content: Cow<'a, str>,
    /// The style of the span.
    pub style: Style,
}
```

When you render an instance of `Paragraph`, the `Paragraph` widget is passed to a
[`Paragraph`'s `render`](https://github.com/ratatui-org/ratatui/blob/e5caf170c8c304b952cbff7499fd4da17ab154ea/src/widgets/paragraph.rs#L253-L268)
function along with the `Buffer`.

The implementation of `render` loops through the content of the `Text` struct in the `Paragraph`
widget and puts the content in the appropriate `Cell` locations using methods exposed on the
`Buffer` struct.


As another example, here's a snippet of the [`render` method for `Block`]:

```rust
    fn render(self, area: Rect, buf: &mut Buffer) {
        buf.set_style(area, self.style);
        let symbols = self.border_set;

        // Sides
        if self.borders.intersects(Borders::LEFT) {
            for y in area.top()..area.bottom() {
                buf.get_mut(area.left(), y)
                    .set_symbol(symbols.vertical_left)
                    .set_style(self.border_style);
            }
        }
        // --snip--

        // Corners
        if self.borders.contains(Borders::RIGHT | Borders::BOTTOM) {
            buf.get_mut(area.right() - 1, area.bottom() - 1)
                .set_symbol(symbols.bottom_right)
                .set_style(self.border_style);
        }
        // --snip--
    }
```

[joshka]

Lots of comments at a very high level (there's some background discord chat on this that provides more context for anyone else reading).

Approving as it's much better than what was there and nothing in the comments is necessary to ship this.

Some general comments - there's a few sentences that start with nothing words ("basically what this", "essentially has a" and a lot of passive voice ("terminal.flush is called"). I think the ratio of code to text gets in the way of providing some good narrative info.

I think it would be worth presenting the methods from the caller's perspective rather than the ratatui code perspective (i.e. buf.set_string(...) rather than pub fn set_string ...)

[kdheepak]

Thanks for the extremely helpful and detailed comments! I took another stab at it and pushed a new commit with a number of changes. I'm going to take a break and come back to it hopefully with a more fresh perspective.

[kdheepak]

@joshka I'm going to merge this. I'll address any additional comments you or others have in future PRs.