Improve public rustdocs

[joshka]

Summary

Improve Termina's public rustdocs so the crate is easier to evaluate and use as a terminal backend.

This is a docs-only change. It expands module, type, variant, and method documentation across the public API so docs.rs readers can understand the terminal, parser, event, escape-sequence, and style surfaces without reading the implementation first.

Motivation

Ratatui has an open request to consider Termina as a backend:

ratatui/ratatui#1784

Before that is practical, Termina needs a stronger user-facing documentation surface. This pass documents the current API rather than changing behavior.

I maintain Ratatui and crossterm, so I tried to bring that support and review experience into this pass. In particular, the docs now call out recurring sources of user confusion around terminal input: key press/release events, terminal-dependent key encoding, modifier handling, mouse coordinates, raw/cooked mode behavior, and platform differences.

What changed

• Added module-level overviews and examples for the crate, events, parser, terminal handles, escape sequences, and styling.
• Expanded docs for public enums, structs, variants, fields, and methods.
• Added examples for event reading, parser usage, CSI/OSC/DCS construction, SGR styling, colors, and terminal operations.
• Linked protocol concepts to local rustdoc types where possible and to public specs/docs where useful.
• Clarified terminal-specific behavior such as key press/release events, character normalization, mouse coordinates, raw/cooked mode differences, and Windows legacy input.
• Preserved implementation context for upstream influences such as crossterm, termwiz, xterm, Kitty keyboard protocol, and DEC/xterm terminal specs.

Review Notes

This is intentionally a broad documentation pass. I manually reviewed and steered the public docs for correctness and tone, with extra attention to the event, parser, terminal, and style APIs.

The main remaining review caveat is the CSI/DCS/OSC reference docs. Those sections are repetitive protocol enum documentation, and I have not manually reviewed every variant with the same depth as the rest of the crate. The examples, links, and rustdoc formatting for those sections were validated mechanically.

No runtime behavior is intended to change.

Validation

Ran:

cargo fmt
RUSTDOCFLAGS='-D missing_docs -D rustdoc::broken_intra_doc_links' cargo doc --no-deps --all-features
RUSTDOCFLAGS='-D rustdoc::broken_intra_doc_links' cargo doc --no-deps --all-features --document-private-items
cargo clippy --all-targets --all-features
cargo test --all-features

[the-mikedavis]

This is awesome, thanks @joshka! I want to merge this basically as-is. I have one nit though: I'd also update the README to note that "CREDIT" comments have moved into implementation notes sections (https://github.com/helix-editor/termina#credit)

[the-mikedavis]

Looks like the docs CI found a nit on Windows as well

[joshka]

This got reformatted by markdown lint. I usually use 100 char lines and align tables. Hope that's ok here. It generally edits easier that way. (Easier diffs in github etc.). Happy to revert that part as I know it's fairly subjective choice.

[the-mikedavis]

Ah yeah I'd prefer to keep the style of the README mostly unchanged. I like to avoid hard wrapping in markdown. Making the table slimmer seems alright though, it's very wide right now. Maybe we can say "terminal dependent" and have a footnote or cross/star symbol that says that it depends on Kitty keyboard support below the table.

[joshka]

Done 05b5fe7

[joshka]

Both comments addressed.

[the-mikedavis]

Thanks again!