search

jazzfool / reclutch

Rust UI Core
Other
157 stars 4 forks source link

Tracking issue: Documentation #5

Closed fogti closed 4 years ago

fogti commented 5 years ago

The overall documentation seems to be quite good, but especially the rustdoc documentation/doc-comments should be created/improved. The target of this would be, that every public API component is documented and the API is (at least mostly) understandable using rustdoc (later possibily viewable via docs.rs) doc comments alone.

jazzfool commented 5 years ago

Most (if not all) of the user facing display API is documented. Only the events API remains to be documented.

fogti commented 5 years ago

I already documented large parts of the newly introduced cascade API, althrough general core principles of the crate should be documented too.

fogti commented 5 years ago 
warning: `[DisplayClip::Rectangle::rect]` cannot be resolved, ignoring it...
   --> reclutch/src/display/mod.rs:371:37
    |
371 |         /// Set to true if [`rect`](DisplayClip::Rectangle::rect) isn't pixel-aligned.
    |                                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ cannot be resolved, ignoring
    |
    = note: `#[warn(intra_doc_link_resolution_failure)]` on by default
    = help: to escape `[` and `]` characters, just add '\' before them like `\[` or `\]`
jazzfool commented 5 years ago

My mistake, fixed. Thanks for pointing it out.

fogti commented 5 years ago

reclutch::display::Vector should be documented, because the name does not directly imply that it's a 2D floating-point vector.

jazzfool commented 5 years ago

Good point; 897188e.

fogti commented 4 years ago

I think the documentation should be cross-checked for inconsistencies after the lastest merges. I know the README.md files are outdated.

16 should fix that.

jazzfool commented 4 years ago

Yep, merged.

jazzfool commented 4 years ago

I'm quite confident about the documentation. I've fixed up all the intra-doc links, which resolve correctly with cargo +nightly doc --all-features.