Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve inline docs #2460

Merged
merged 36 commits into from
Jun 7, 2024
Merged

Improve inline docs #2460

merged 36 commits into from
Jun 7, 2024

Conversation

ealmloff
Copy link
Member

@ealmloff ealmloff commented May 29, 2024

The dioxus docsite is pretty good at getting you started with dioxus, but our inline and docs.rs docs are currently pretty sparse in comparison. This PR improves the inline docs for the core, html, hooks, and signals crates

Goals:

  • Provide more examples for common items
    • eval examples
    • onmounted examples
    • attributes rsx syntax
    • elements rsx syntax
    • resource
    • memo
    • reactivecontext
    • Routable
    • FromQuery
    • FromQueryArgument
    • FromRouteSegment
    • FromRouteSegments
    • ToRouteSegments
    • use_effect
    • rsx
  • Make common items more discoverable with doc(alias)
    • aliases for html names -> rust names on attributes
    • use_state -> use_signal
    • ref -> onmounted
  • Improve trait not implemented errors with diagnostics
    • closure maybe async return
    • props not implemented
    • component not implemented
    • Routable/FromQuery/FromQueryArgument/FromRouteSegment/FromRouteSegments/ToRouteSegments
    • Dependency
  • Provide better references for common errors on methods where they can occur
    • event handle errors
      • function requires argument type to outlive 'static
      • use of moved value: your_value value used here after move
    • spawn errors
      • async block may outlive the current function, but it borrows value, which is owned by the current function
      • use of moved value: value. move occurs because value has type YourType, which does not implement the Copy trait
  • Update dioxus crate readme
    • Mention renderer features, signals, and the router
    • Don't go into detail about custom hooks etc. Just link to more complete docs

Fixes #2390

@ealmloff ealmloff added documentation Improvements or additions to documentation hooks Changes to built-in hook package signals Related to the signals crate html Related to the html crate labels May 29, 2024
@ealmloff ealmloff marked this pull request as ready for review June 3, 2024 17:47
@ealmloff ealmloff added the backport PRs that should be back ported to the last release label Jun 6, 2024
Copy link
Member

@jkelleyrtp jkelleyrtp left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wow. So much work went into this.

At some point we should propagate more of this onto the guide itself too.

@jkelleyrtp jkelleyrtp merged commit 0127501 into DioxusLabs:main Jun 7, 2024
9 checks passed
@ealmloff ealmloff deleted the better-inline-docs branch June 7, 2024 01:16
DogeDark pushed a commit to DogeDark/dioxus that referenced this pull request Jul 3, 2024
Improve inline docs

* improve incorrect event handler return error message

* Improve event handler docs

* document the eval functions

* document spawn and common spawn errors

* fix event handler docs

* add notes about how you use attributes and elements in rsx

* add doc aliases for attributes and events we rename

* add some more aliases for common search terms

* don't doc ignore any public examples in core

* don't ignore public doc examples in ssr

* don't ignore examples in the dioxus package readme

* add a warning when you launch without a renderer enabled

* fix some outdated element docs

* add a bunch of examples to resource

* add notes about desktop events

* add more docs for use_resource

* add on_unimplemented hint to Dependency

* fix some unresolved links

* add examples to each of the router traits

* add not implemented errors for router traits

* add an example to the routable trait

* expand rsx macro docs

* improve memo docs

* update the dioxus readme

* mention dioxus crate features in the docs

* fix a bunch of doc tests

* fix html doc tests

* fix router doc tests

* fix dioxus signals doc tests

* fix dioxus ssr doc tests

* fix use_future example in the hooks cheat sheet

* add a javascript alias for eval

* fix hook explanation values

* remove unused embed-doc-image dependency
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
backport PRs that should be back ported to the last release documentation Improvements or additions to documentation hooks Changes to built-in hook package html Related to the html crate signals Related to the signals crate
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Docs have a couple outdated examples
2 participants