Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Drawer reference documentation could be improved #1020

Closed
1 of 6 tasks
dclamage opened this issue Feb 26, 2021 · 2 comments · Fixed by #8955
Closed
1 of 6 tasks

Drawer reference documentation could be improved #1020

dclamage opened this issue Feb 26, 2021 · 2 comments · Fixed by #8955
Labels
docs Related to docs enhancement New feature or request
Milestone

Comments

@dclamage
Copy link
Contributor

dclamage commented Feb 26, 2021

Is your feature request related to a problem? Please describe.
In general, the reference documentation isn't too useful and I end up having to either cross-reference the examples and hope it covers what I want to do, or reference the actual source code to a component. It's been rare for the reference documentation on its own to actually be enough to let me figure out how to do what I want to do with a component.

Since this is too general of an issue, I figured I'd focus on the Drawer component as it demonstrates a lot of the issues that I see, and maybe fixing that can be expanded in a general way to fix many of the other reference pages as well.

Describe the solution you'd like
Take a look at the Drawer documentation. There are several ways that important information is missing:

  • 1) Fixed: If true, drawer will be fixed. Well, ok, that much is clear because it's a boolean. But what does it actually mean for a drawer to be fixed?

  • 2) ChildContent is present as an attribute, but this is not how that particular property works in Blazor. Perhaps this can be special cased in the documentation to say that this component supports rendering child component content, and what the behavior of that is for this specific component.

  • 3) Anchor, Color, Variant, Breakpoint, ClipMode are all enums but the possible enum values and what they do are not mentioned. Perhaps these can be clickable to visit a reference page for those enum values. If there's any special casing for what those enum values mean for this particular component, or if only particular ones are supported, then that should mentioned in the documentation.

  • 4) There are related child and parent components that are commonly used or even expected to be used in conjunction with the Drawer component, such as MudLayout, MudDrawerHeader, and others. Having links to those components with an idea of whether they're generally a parent, child, or sibling component would be helpful for context and easy navigation.

  • 5) Drawer inherits from MudComponentBase and that should be mentioned. If it inherits from a different base component there could be a link to that. If any components inherit from it, there could be a link to those as well.

  • 6) A link to the sourcecode of the razor and (cs)[https://github.com/Garderoben/MudBlazor/blob/master/src/MudBlazor/Components/Drawer/MudDrawer.razor.cs] file on GitHub could be useful if all else fails.

Describe alternatives you've considered
n/a

@GioviQ
Copy link

GioviQ commented Sep 4, 2023

I discovered now I do not have to use MudDrawerContainer inside MudLayout

@jperson2000
Copy link
Sponsor Contributor

I'll be revisiting all XML documentation over the next few months, so I'm happy to take this on. Thanks for taking the time to report this issue!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Related to docs enhancement New feature or request
Projects
None yet
Development

Successfully merging a pull request may close this issue.

5 participants