Triage clippy pedantic lint `must_use_candidate`

[Ben]

currently, #![warn(clippy::pedantic)] throws a lot of these warnings if you remove the allow for it. This issue is to discuss whether or not having #[must_use] is beneficial, and if so, in what cases.

[arn-the-long-beard]

Hello 😄
Thank you for the initiative !

Well here is the doc I found https://doc.rust-lang.org/reference/attributes/diagnostics.html#the-must_use-attribute

So from what I understand, #[must_use] is used for a specific item and it will throw a warning if the item is not used. Is it right ?

[Ben]

Yeah. for example, the std library Result type has this:

#[must_use = "this Resultmay be anErr variant, which should be handled"]

so when you try to compile this

fn returns_result() -> Result<(),()> {
    Ok(())
}
fn main() {
    returns_result();
}

you get this warning

warning: unused `std::result::Result` that must be used
 --> src/main.rs:6:5
  |
6 |     returns_result();
  |     ^^^^^^^^^^^^^^^^^
  |
  = note: `#[warn(unused_must_use)]` on by default
  = note: this `Result` may be an `Err` variant, which should be handled

this warning can be resolved with let _ = returns_result();

To relate this to seed-routing, we can document where things really should be used, and use it as a prompt to think about the best way to present the result. Let's look at two examples:

// src/router/url.rs
pub fn convert_to_string(query: &IndexMap<String, String>) -> String

// src/router/mod.rs
pub fn forward(&self) -> bool

A library user that doesn't use the String result is most likely just adding code-bloat, so it makes a strong candidate for #[must_use]. I see this example as relatively straight forward decision to make

On the other hand, using the forward e.g., it's not so clear... it's probably a good idea to force the user to opt out of checking the result, and if successful, to have the new Route handy. Changing it to pub fn forward(&mut self) -> Option<Route> will do this. Alternatively, returning Result<(), RoutingError> (which might be good to add, but that's in the future) would tell the user if forward worked or not, and if not, why (E.g. because already at head of history, but more complex reasons could be allowed for in the future, such as changes in permissions) and comes with the benefit of not increasing the refcount of the Route. we could take the simple resolution and add #[must_use], but having this warning around until we decide what the best action is in the long run serves as a flag for tech-debt.

Not as straight forward.

[Ben]

I can make a commit with the changes that seem to make sense and link it in this discussion. That way there is something a bit more concrete to refer to when discussing what changes to make specifically.

[arn-the-long-beard]

Hey 😃

#[must_use] seems to be a good way to indicate users how to use the Router API. I think it is very smart that you came out with it.

Let's use it in a tactical way for them 👍

[arn-the-long-beard]

Hey should we start to identify the places where we can use the #[must_use] ?

[arn-the-long-beard]

created a new issue #13 to apply our discussion 😃

[arn-the-long-beard]

I close this issue since we should use the attribute.