Docs: Refactor API Documentation Generator

[jperson2000]

Description

This update refactors the API Documentation generator to add several features:

• Strongly typed documentation objects for ApiPage.razor to use
• Improved trimmability by removing all Reflection code from Blazor pages
• Support for "documentation coverage" metrics shown during builds

The new documentation generator has these features:

• Support for <summary> and <remarks> elements
• Support for the <c> element (converted to <code>)
• Support for the <para> element (converted to <p>)
• Support for HTML in XML documentation comments
• Support for links to members in the same class or any base class
• Support for <see cref links

This update also adds Documentation Coverage metrics during builds:

XML Documentation Coverage for MudBlazor:

Types:      69 of 169 (41%) other types
Properties: 1458 of 2451 (59%) properties
Methods:    170 of 2093 (8%) methods
Fields:     12 of 667 (2%) fields/enums
Events:     0 of 6 (0%) events

API Builder: WARNING: 280 types have XML documentation which couldn't be matched to a type.
API Builder: WARNING: 569 properties have XML documentation which couldn't be matched to a type's property.
API Builder: WARNING: 653 methods have XML documentation which couldn't be matched to a type's property.
API Builder: WARNING: 4 events have XML documentation which couldn't be matched to a type's property.
API Builder: WARNING: 176 fields have XML documentation which couldn't be matched to a type's property.

This update also makes a few minor code cleanup changes:

• The Paths class is now static

How Has This Been Tested?

The TestsForApiPages test generator was updated to use the new Api Blazor page when generating tests. A big change is that we now test all public types, not just types inheriting from MudComponentBase. This resulted in an additional 400 tests being generated during builds.

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.49%. Comparing base (28bc599) to head (9868847).
Report is 239 commits behind head on dev.

Additional details and impacted files

@@            Coverage Diff             @@
##              dev    #8903      +/-   ##
==========================================
+ Coverage   89.82%   90.49%   +0.66%     
==========================================
  Files         412      398      -14     
  Lines       11878    12375     +497     
  Branches     2364     2403      +39     
==========================================
+ Hits        10670    11199     +529     
+ Misses        681      627      -54     
- Partials      527      549      +22     

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

[danielchalmers]

Just checking: does it support <br/>? I've been using that recently instead of <para> because it's more compact. para might want a little more space in the docs compared to br (but much less than before), what do you think?

[ScarletKuro]

Would you able to do this testing #3595
To see that nothing unexpected got broken?

[ScarletKuro]

Would you able to do this testing #3595 To see that nothing unexpected got broken?

Maybe I'd be good idea to leave the code of this in the tool folder so anyone could run it at anytime.

[iwis]

Why did you change LayoutProperties.DefaultBorderRadius to DefaultBorderRadius in the description of MudChipset.Label?

Some incorrect descriptions:
MudChipSet<T>.Comparer
MudHighlighter.Markup
MudMessageBox.YesButton

I only checked a few pages manually. When I was refactoring the code for API documentation, often some change was manifested only in a bug in a few properties on a few pages. This is why I wrote #3595 to be sure I don't break documentation. As you see, unfortunately, manual testing isn't enough :(

[jperson2000]

Just checking: does it support <br/>? I've been using that recently instead of <para> because it's more compact. para might want a little more space in the docs compared to br (but much less than before), what do you think?

I'm pretty sure <br/> and other tags would be supported since the new code uses MarkupString. I'll be sure to test that.

[jperson2000]

Why did you change LayoutProperties.DefaultBorderRadius to DefaultBorderRadius in the description of MudChipset.Label?

Some incorrect descriptions: MudChipSet<T>.Comparer MudHighlighter.Markup MudMessageBox.YesButton

I only checked a few pages manually. When I was refactoring the code for API documentation, often some change was manifested only in a bug in a few properties on a few pages. This is why I wrote #3595 to be sure I don't break documentation. As you see, unfortunately, manual testing isn't enough :(

Thanks for checking some pages! I agree, it's really tough to get every detail just right, like dealing with reflection names. Hopefully I can get some automated tests built from your great test code.

[henon]

There's a "critical types" list which is just a whitelist of the primary MudBlazor components, but this is only used to calculate documentation coverage metrics. We could get rid of it and calculate docs coverage for ALL types, but this would include types users don't see and be a pretty low percentage.

Wouldn't a blacklist be better suited here? So when we add a component we don't have to think about extending the white list. Of course, if we add internal support types we have to remember, but even if we forget, the worst that can happen is that an internal type is exposed in the api docs for a time until we black list it.

[henon]

I love that you added the search feature, but yeah, thinking again browser search pretty much does the same. When I said I'd love integration of the API info with search I meant the primary search box in the app bar. So for instance, if you type a parameter name, components will be listed that have that parameter. Not sure if you understood it this way.

[danielchalmers]

FYI getting this error from /api/mudalert or /api/alert (or any other) on the MudBlazor.Docs.WasmHost project

Microsoft.AspNetCore.Components.WebAssembly.Rendering.WebAssemblyRenderer[100]
      Unhandled exception rendering component: Object reference not set to an instance of an object.
System.NullReferenceException: Object reference not set to an instance of an object.
   at MudBlazor.Docs.Models.ApiDocumentation.GetType(String name) in \src\MudBlazor.Docs\Models\Generated\ApiDocumentation.cs:line 29
   at MudBlazor.Docs.Pages.Api.Api.OnParametersSet() in \src\MudBlazor.Docs\Pages\Api\Api.razor.cs:line 33
   at Microsoft.AspNetCore.Components.ComponentBase.CallOnParametersSetAsync()
   at Microsoft.AspNetCore.Components.ComponentBase.RunInitAndSetParametersAsync()

---

Some more ideas since I think my review was requested. Again, just my thoughts, not demands 😅

the breadcrumbs could replace Inheritance as it's much more compact

(remove ^)

Breadcrumbs position

could go above the header

Breadcrumbs accessibility

https://developer.mozilla.org/en-US/docs/Web/CSS/Layout_cookbook/Breadcrumb_Navigation#accessibility_concerns

should have some kind of indicator for hover? (im not sure)

Breadcrumbs active

the ones that aren't active should have a different color, maybe just darker grey.

Better ^

Worse but an option (primary color) ^

should the headers look like they're a part of the table? (they have lines)

also i wonder if each header should have their own sort so it's always accessible? that would kill a few birds with one stone

the space between each section could be reduced

Links could be default instead of Body1 so they look like normal links

subtext

subtext could semantically be subtitle1 instead of body1 (slightly different)

Filters

Personally would try to simplify as much as possible so removing these and moving the "Inherited" info into the rows directly might work in order to save more space

Or better: an icon next to it that indicates there is a parent and when you hover over it it tells you where it comes from

If you still wanted to be able to collapse them, a simple clickable collapse arrow could do the trick

basically with the goal of keep the screen clean with less elements so people focus directly on the docs as their first instinct. dont want to scare anyone away because of extra buttons etc (sounds stupid i know lol)

Accessibility

This area in the docs should have aria-labels for relevant areas and properties should be tabbable (currently all are skipped over). im aiming for accessibility as a priority now

[jperson2000]

Alrighty, after almost a month, I think this Docs refactor is nearly ready to review! There are some things I still have to improve like documenting method parameters and enums/fields, but I think the site is in good shape to look at. Here are the major differences to look for:

• The API docs exist for all public types, not just types inheriting from MudComponentBase. This helps to cover non-component documentation such as TableState and others.
• The API test generator now generates tests for all public types. The tests assert that documentation was actually found for the page. For types which are Mud components, the tests also assert that an example link was found.

Let me know if you'd like any UI changes, and I'll bring this out of draft once I have the last pieces done in about 2-3 days. Thanks @ScarletKuro @henon @danielchalmers @mckaragoz @Anu6is for your valuable feedback as always!

Steps to Test

1. From this branch, run MudBlazor.Docs.Compiler to generate new docs and tests on your machine.
2. Change the startup project to Server or WASMHost and run.
3. Navigate to any API component page.

[ScarletKuro]

Can we move this code in a reusable utility? This and code in the DocumentedProperty.cs look the same.

[danielchalmers]

Thanks for taking into account so much of my feedback, I appreciate that a lot :)
Everything looking great, big improvement over the v6 docs.

On mobile:

• Horizontal padding limits amount of info that can be seen
• Header is right-to-left (normally it's on the left side)
• The select ("Name") doesn't have a hint about its function
• May need very slightly more vertical padding between rows so they don't blend into each other

Accessibility (cc @igotinfected what do you think? screenshots above):

• Should you be able to tab between rows?
• Contrast between code blocks and background is low in dark mode
  • Swapping the row hover and default background color might work
  • Also might help to replace the code blocks with simple color text (aka remove the background)
• Aria labels ("Property name", "Property type", "Property description")?

Other:

• I think I was wrong when I said to skip documenting RightToLeft because I didn't think about it being in the docs