Docs: improve general methods documentation

[Valentin271]

Problem

There is not enough documentation in the widgets' methods (and other relative elements such as Title or Padding). While most of them are simple and require almost no documentation, some other can be ambiguous.

This was a major pain point for me while discovering the library (as a user and as a contributor).

Solution

Add documentation

Alternatives

None

Additional context

I'm totally down to work on it, I just want to advertise this work for users and possibly interested contributors.

Elements missing documentation, grouped by widget :

• BarChart, Bar (docs(barchart): add documentation to BarChart #449)
• Block, Padding, BorderType (docs(Block): add documentation to Block #469)
• Chart, Axis, Dataset (docs(chart): document chart module #696 )
• Gauge (docs(Gauge): add documentation to Gauge #514)
• List, ListState, ListItem (docs(list): add documentation to the List widget #669)
• Paragraph (docs(paragraph): added documentation to the "alignment" method #467)
• Sparkline, RenderDirection (docs(Sparkline): add documentation #648)
• Table (docs(table): added documentation for the 'new' method of the 'table' widget #471, chore(table): cleanup docs and builder methods #638)
• Tabs (docs(tabs): add documentation to Tabs #535)

There are other elements that need documentation, but I think they can be addressed later in an other issue.

---

Would it be useful to warn (and deny, once completed) on missing doc? See https://doc.rust-lang.org/rustdoc/lints.html#missing_docs

[Valentin271]

Also, I think documentation and maybe good first issue are good labels here. Thanks

[joshka]

Would it be useful to warn (and deny, once completed) on missing doc? See https://doc.rust-lang.org/rustdoc/lints.html#missing_docs

Yes. Definitely! (Probably worth doing per file once they are documented well)

[joshka]

P.S. I recommend using an LLM (e.g. OpenAI / Llama / Claude) to help make this quicker to implement. Obviously validate the output and don't just accept AI hallucinations as gospel :)

Perhaps add some general doc guidelines to this issue or point to some existing ones if you're aware of them.
Some key points I'd worry about are (please add some more if you have them):

• keep line length to 100 chars (to make it easy to maintain) - the vscode rewrap extension is good for this
• first line is summary, second line blank, third onwards is more detail.
• the main type doc comment should talk about the general features that the widget supports and introduce the concepts pointing to the various methods. Focus on interaction with various features and giving enough information that helps understand why you might want something. Also point out alternates
• any example code is as simple as possible

Also, another way to contribute to the documentation is to improve the examples so they cover each feature a little better. the examples are scraped automatically to provide examples in the docs page (use cargo +nightly doc -Zunstable-options -Zrustdoc-scrape-examples --all-features --open or run bacon and press d). A recently updated example is the block example, which gives the following output without any changes to the block's comments:

I've been thinking a bit about how and whether to add images to the doc comments. Like perhaps it would be worth chopping the block example up and putting an image of each part of it directly into the doc comment (this is fairly simple to automate with VHS, but requires a lot of effort to do at scale).

[DreadedHippy]

Hi,

I'm interested in fixing this issue. I'd like to start with "Paragraph" but I'm not very sure what needs changing. Could you provide more detail please?

It is unchecked in the list above but it doesn't seem to be missing documentation

[Valentin271]

Hello, it seems the Paragraph has been documented a little bit more since I wrote the list. Still it is missing one docstring for the alignment method. (You can add #![warn(missing_docs)] at the top of the file to see it).

The main type doc can also be improved by referencing to the different concepts of Paragraph.

You can also look here for some guidelines.

[DreadedHippy]

Alright, thank you very much for this.

I'll begin documenting Paragraph and move from there

[joshka]

Some guidelines to consider:

• https://rust-lang.github.io/api-guidelines/documentation.html
• https://github.com/jntrnr/rfcs/blob/front_page_styleguide/text/0000-api-doc-frontpage-styleguide.md
• https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md
• https://github.com/ratatui-org/ratatui/blob/main/CONTRIBUTING.md#documentation

How about writing a concise checklist based on the above links (customized for Ratatui) that helps evaluate whether the docs are complete?

[DreadedHippy]

Alright, I will do this

[joshka]

Also no need to close #467 - this is fine to add as is with the suggested changes.

[DreadedHippy]

Some guidelines to consider:

• https://rust-lang.github.io/api-guidelines/documentation.html
• https://github.com/jntrnr/rfcs/blob/front_page_styleguide/text/0000-api-doc-frontpage-styleguide.md
• https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md
• https://github.com/ratatui-org/ratatui/blob/main/CONTRIBUTING.md#documentation

How about writing a concise checklist based on the above links (customized for Ratatui) that helps evaluate whether the docs are complete?

• Are all methods documented?
• Are all enums documented?
• Are all documented types hyperlinked?
• Are the examples given the minimum viable examples?

Do you mean something like the above?
@joshka

[joshka]

Do you mean something like the above? @joshka
Yep

• All types, traits, methods, and enums are documented (add #![warn(missing_docs)] once a module is complete)
• All mentions of a type or function are hyperlinked like [`Layout`]
  To make it easier to read the docs in the doc comment, use references at the end of the comment: [`Layout`]: crate::layout::Layout
• Interactions between methods are documented at the type level
• Methods include Panic / Error details
• Every public module, trait, type, and function has a simple example. The intent of the example is to show why someone would want to use the item, not just how to use it.
• Examples follow conventions:
  • use a ```plain code fence to show rendered widgets (unless obvious)
  • hide imports in method examples (except: types not part of the prelude / not obvious from context)
  • use use ratatui::prelude::* to avoid common imports
  • use Style::new().red() rather than Style::default().fg(Color::Red)
  • use ? rather than unwrap

[Valentin271]

nvim with rust-analyzer does it automatically for me. For vscode there is a rewrap extension. There are probably similar extension for other editors.

[farmeroy]

Is the list of widgets that still need documentation up to date? I was working with various List widgets and Table and would be happy to try to improve those docs

[joshka]

Is the list of widgets that still need documentation up to date? I was working with various List widgets and Table and would be happy to try to improve those docs

I wouldn't count on it being so - the latest alpha release docs are available at https://docs.rs/ratatui/0.23.1-alpha.6/ratatui/index.html - feel fee to jump in wherever things are missing or could be better explained.

[Valentin271]

I've just checked and it is indeed up to date, those widgets are still missing documentation.