Docs: MudColorPicker: Added XML Documentation for Public Members

[jperson2000]

Description

This update adds XML documentation for MudColorPicker and related classes:

• ColorPickerMode
• ColorPickerView

This update also removes prior documentation for the RightToLeft property in some components because it cannot be set via the Razor editor (and thus no documentation can be displayed).

• MudAlert
• MudButtonGroup
• MudCarousel
• MudCarouselItem
• MudChart

Then, XML documentation was added for the MudRTLProvider class.

How Has This Been Tested?

This was tested by observing the example source code for MudColorPicker.

Type of Changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation (fix or improvement to the website or code docs)

Checklist

• The PR is submitted to the correct branch (dev).
• My code follows the code style of this project.
• I've added relevant tests.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 90.48%. Comparing base (28bc599) to head (feee267).
Report is 186 commits behind head on dev.

Additional details and impacted files

@@            Coverage Diff             @@
##              dev    #8872      +/-   ##
==========================================
+ Coverage   89.82%   90.48%   +0.65%     
==========================================
  Files         412      419       +7     
  Lines       11878    12197     +319     
  Branches     2364     2381      +17     
==========================================
+ Hits        10670    11036     +366     
+ Misses        681      627      -54     
- Partials      527      534       +7     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[jperson2000]

I hope you're having a good weekend @henon @danielchalmers ! There are a couple of things to note in this PR:

• The documentation for cascading parameter RightToLeft was removed because this property can't be seen when editing Razor files, thus no documentation could be seen. Instead, the MudRTLProvider component was documented.
• Regarding "HSL" colors, the MudColor class uses the terms "lightness" as well as "luminance" for the "L" in "HSL". This was standardized to "lightness", but let me know if you prefer another way.

As always, thanks for taking the time to review!

[henon]

Lightness is correct.

[henon]

I am no native speaker but somehow this construction with whether still bothers me: Whether text is displayed Right-to-Left (RTL).. Wouldn't the simple statement Displays text Right-to-Left (RTL). be better?

[danielchalmers]

I am no native speaker but somehow this construction with whether still bothers me: Whether text is displayed Right-to-Left (RTL).. Wouldn't the simple statement Displays text Right-to-Left (RTL). be better?

@henon The goal should be to keep it short to fit on the website so I think that's an improvement.

Here's some ChatGPT magic to see what it could look like:

---

Here are the changes I made to the documentation comments in your C# code to reflect the new style:

1. Changed:

   /// Whether alpha transparency options are shown.

   To:

   /// Displays alpha transparency options.

2. Changed:

   /// Whether the color field will be displayed.

   To:

   /// Displays the color field.

3. Changed:

   /// Whether the switch to change the color mode will be displayed.

   To:

   /// Displays the switch to change the color mode.

4. Changed:

   /// Whether the text inputs, color mode, and switch will be displayed.

   To:

   /// Displays text inputs, color mode, and switch.

5. Changed:

   /// Whether hue and alpha sliders are displayed.

   To:

   /// Displays hue and alpha sliders.

6. Changed:

   /// Whether a preview of the color is displayed.

   To:

   /// Displays a preview of the color.

7. Changed:

   /// Whether changes to the bound value only occur when HSL values change.

   To:

   /// Changes to the bound value occur only when HSL values change.

8. Changed:

   /// Whether the selected color can continue to change while the mouse button is down.

   To:

   /// Allows the selected color to continue changing while the mouse button is down.

These changes make the documentation more concise and align with the new style you're aiming for, focusing on action rather than condition.

To further streamline and improve your documentation, especially if you want it to be concise, consider these additional styles:

1. Active Voice: Using active voice can make sentences shorter and more direct. For instance, "Displays the color field" is already in active voice and is more straightforward than a passive construction.

2. Imperative Mood: This is particularly useful for instructions or actions, making commands more succinct. It's already similar to the changes made, but for other parts of your documentation, phrases like "Set color," "Change mode," or "Select from palette" can be effective.

3. Eliminate Redundancies: Check for any redundant phrases or implied information that can be omitted without losing meaning. For example, "Displays the color field" could potentially be "Shows color field" if the context already implies display settings.

[danielchalmers]

We need to update the docs viewer on the website so it doesn't have these big gaps:

[jperson2000]

We need to update the docs viewer on the website so it doesn't have these big gaps:

#8903 was started to support XML elements like <c>, <para>, and <see cref

[jperson2000]

Alrighty, I've rewritten all of the "Whether" boolean docs to use more active language. That was a great suggestion because it slimmed down the sentences while making them more readable. Ready to review!

[danielchalmers]

Looks really great, love the changes. Hope you don't mind the number of notes - Most of it is subjective and is not necessarily better or worse but I wanted to get some more ideas going!

[jperson2000]

Looks really great, love the changes. Hope you don't mind the number of notes - Most of it is subjective and is not necessarily better or worse but I wanted to get some more ideas going!

All good, @danielchalmers ! The extra scrutiny is smart at the start of this effort so we can all get a good standard to follow. That will make the next several docs PR's go smoothly!

[jperson2000]

I'm going to sneak in one more commit to fix up MudAppBar which I missed. Should just be a few minutes.

[henon]

Very nice, thanks a lot @jperson2000