Add beginner tip to ErrorBoundary #2385
Conversation
This might seem simple, but the nuances of types and traits confuse many people learning the language.
leptos/src/error_boundary.rs
Outdated
| @@ -51,6 +51,28 @@ use leptos_reactive::{ | |||
| /// {move || { | |||
| /// /* etc. */ | |||
| /// ``` | |||
| /// | |||
| /// ## Beginner's Tip: ErrorBoundary Requires Your Error To Implement std::core::Error. | |||
There was a problem hiding this comment.
std::core::Error here and elsewhere should be std::error::Error
leptos/src/error_boundary.rs
Outdated
| /// | ||
| /// ## Beginner's Tip: ErrorBoundary Requires Your Error To Implement std::core::Error. | ||
| /// ErrorBoundary requires your `Result<T,E>` to implement `IntoView`. | ||
| /// `Result<T,E>` only implements `IntoView` if E implements `std::core::Error`. |
There was a problem hiding this comment.
These types should ideally be links if possible. You can test whether the links work correctly with cargo doc --no-deps --open and then check out this page to see if it looks right.
leptos/src/error_boundary.rs
Outdated
| /// ## Beginner's Tip: ErrorBoundary Requires Your Error To Implement std::core::Error. | ||
| /// ErrorBoundary requires your `Result<T,E>` to implement `IntoView`. | ||
| /// `Result<T,E>` only implements `IntoView` if E implements `std::core::Error`. | ||
| /// So, for instance, if you pass a Result<T,String> where T implements IntoView |
There was a problem hiding this comment.
The types here should be in backticks
|
Hey, Greg! Thanks for the feedback here. The github editor is really convenient but it isn't an adequate replacement for going through a methodology and you've laid down the beginnings of. I know your time is better spent elsewhere then editing docs, and I appreciate your patience and your willingness to onboard new contributors like myself. I'm going to post all these changes, but- I also wanted to touch base with you and see if we could clarify/formalize a standard for contributors to the documentation. I think it'd be awesome to have a document that gives guidelines (so you don't have to repeat yourself, I think this is the second time you've told me to tic types or link places, sorry sorry :) ).. but we could also link to it right on the front page of docs.rs. Something like, "Yes you can contribute to the leptos docs. Your unique perspective is appreciated and needed! Click here to learn how you can help." and something like link to the guidelines (they probably already exist somewhere) right at the top of the docs.rs/leptos. A classic top of the page marketing attention-grabbity-grabber, to pull more people into the contributor pipeline. One of the things I've been doing is if I have anything with the docs that I'm iffy about or if I have any ideas about how they could improve for my own use case, I just open a pull request. And I don't know about you but I love that energy, but also it could be annoying especially if I keep making the same mistakes or if a dozen other people did to and made the same mistakes! :) One more thought I wanted to run past you before going and doing it, I was planning on doing it for 0.7.0 which is that you know we have the docs, and the examples, and the books (and even more). And basically making a link section at the bottom of each component/other_thing for relevant external docs. It's way too easy to just get stuck reading the docs in your editor, and then even skipping external resources and jumping right to reading source code. Which is awesome but I think of the documentation's importance (it takes up prime real estate, hover over a type and get feedback instantly) could be better utilized by something like having a bunch of links for even deeper dive into whatever your doing. Ideally with that I'd love to saturate the space, hopefully all high quality but just drop so many examples, markdowns, whatever.. i.e completed discord chats... etc. that people are like "ok wow". I forgot all the time which examples showcase what, and also when I'm tired I forget they even exist! In my experience just digging through the example folder is okay to get started but there's a lot of value there! You've put a lot of effort into having really high quality examples that aren't being done justice by users having to go to the repo page and click two maybe even three times to and read the example directory to find what they're looking for. But anyways, I just wanted to connect explicitly and try to understand how you feel and your over all goals for the docs etc general vibe - whatever. Thanks! |
No worries, it's fairly quick for me to leave these comments -- and quicker than going and opening a separate branch and making changes myself, so I really appreciate your work.
I think this is a great idea. Realistically it's not something I'm going to have time to work on in the immediate future, but maybe a bit later this spring. There've been a few others interested in adding to/improving the docs so if there's some other form of group communication that's useful for coordinating that's also good.
Nah not annoying at all, I will just reply to things when I have time. It does not bother me as long as people don't mind waiting for responses 😄
I think cross-references from the docs.rs docs to the book and to examples is a great idea! Especially as things settle down over time, API-wise, which I anticipate really starting with 0.7. (It's hard to keep things in sync otherwise, if they move around.) Really really good idea to be like "here are the docs on
Totally. I appreciate the help and will often leave nits on docs things like this because they aren't linted automatically in CI, but I hope you know I'm grateful for it! |
|
Sounds good! I don't mind waiting, I'm glad as open source maintainer that you are establishing healthy boundaries. That makes me feel confident in the success of the project. Which is important for me when volunteering as well as picking Leptos as a core framework of my projects. I feel aligned on the overall goals of the documentation and it's clear to me where I will add my energy next. This is a doc guideline that I think is helpful, it's seems to be the result of multiple years of communicating guidelines to contributors. It's extensive, and a one-to-one port wouldn't fit the current state of the Leptos project but it appears to have helped align 200+ documentation contributors. The Ory docs, compared to a fully funded project like Stripe, or Github aren't great, but given that it's almost an entire volunteer effort over multiple years they've managed to put together something that ties together various parts of various complicated systems. As I make more examples and documentation changes I'll try to put together all the nits I get into a more stable form and share that in case it's useful as a base. The Ory guidelines, I assume, evolved naturally to normalize contributor behavior so something similar would work here I imagine.
For sure! |
|
Thanks for writing this! |
This might seem simple, but the nuances of types and traits confuse many people learning the language.