Improve option docs

[patrickoliveira15]

This PR enhances the documentation of the Option::map_or method by adding more comprehensive and practical examples. These updates aim to help developers better understand the method's behavior and usage in various scenarios, especially when dealing with Some and None cases.

Changes Made:

1. Added Examples for Clarity:

   • Demonstrated how map_or applies a function to a value when Some is present.
   • Showed how the default value is returned when None is encountered.

2. Introduced a Real-World Use Case:

   • Added an example illustrating how map_or can be used to handle fallback logic, such as generating personalized greeting messages.

3. Improved Readability:

   • Included comments to explain each example, ensuring developers understand the rationale behind each test case.

Updated Examples:

// Using a default value for an empty option.
let empty: Option<i32> = None;
assert_eq!(empty.map_or(0, |v| v * 2), 0); // Default value is used.

// Applying a function to a `Some` value.
let value = Some(21);
assert_eq!(value.map_or(0, |v| v * 2), 42); // Function is applied to `21`.

// Practical example with `Option<&str>`:
let username: Option<&str> = Some("Alice");
let greeting = username.map_or("Hello, guest!".to_string(), |name| format!("Hello, {}!", name));
assert_eq!(greeting, "Hello, Alice!");

let no_username: Option<&str> = None;
let fallback_greeting = no_username.map_or("Hello, guest!".to_string(), |name| format!("Hello, {}!", name));
assert_eq!(fallback_greeting, "Hello, guest!");

Benefits:

• Improved Usability: The examples provide clear, actionable guidance on how to use map_or effectively.
• Increased Accessibility: Developers at all levels can quickly grasp the method's functionality with the added real-world context.
• Aligned with Rust's Philosophy: Enhances documentation to prioritize clarity and developer experience.

If there are additional scenarios or edge cases worth including, I'm happy to expand this PR!

[rustbot]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @jhpratt (or someone else) some time within the next two weeks.

Please see the contribution instructions for more information. Namely, in order to ensure the minimum review times lag, PR authors and assigned reviewers should ensure that the review label (S-waiting-on-review and S-waiting-on-author) stays updated, invoking these commands when appropriate:

• @rustbot author: the review is finished, PR author should check the comments and take action accordingly
• @rustbot review: the author is ready for a review, this PR will be queued again in the reviewer's queue

[compiler-errors]

As @cyrgani noted in #135551 (comment):

I do not believe that any of these cases add anything of value compared to the two existing examples above. They are just more verbose, but showcase no new features or behavior.
If there is a different rationale for this, please try to explain it without lots of vague LLM speech.

[patrickoliveira15]

As @cyrgani noted in #135551 (comment):

I do not believe that any of these cases add anything of value compared to the two existing examples above. They are just more verbose, but showcase no new features or behavior.
If there is a different rationale for this, please try to explain it without lots of vague LLM speech.

Thank you for the feedback! 🙏

I understand your concern about the examples not adding significant value compared to the existing ones. My intention was to provide additional use cases that demonstrate map_or in slightly different contexts, particularly with a focus on clarity for beginners or those less familiar with Rust.

I’m new to Rust, and I truly appreciate the guidance. I’ll take this as an opportunity to refine my contributions and focus on adding meaningful value. If you have any suggestions for beginner-friendly issues or tasks that would be a good starting point, I’d be more than happy to explore them.

Thanks again for taking the time to review my PR! 😊