[Feature Request] Allow component documentation within razor file

[lonix1]

Is your feature request related to a problem? Please describe.

It is convenient to specify both markup and code in a single Foo.razor file. However while it is possible to document the class' members, it's not possible to document the class itself.

For example, MyComponent.razor:

<markup>

@class {

  /// <summary>
  /// Some documentation.
  /// </summary>
  [Parameter] public bool Foo { get; set; }

  //...etc...
}

That member's documentation is recognised. But one cannot document that component itself. So we need this:

MyComponent.razor.cs:

/// <summary>
/// Some documentation.
/// </summary>
public partial class MyComponent : ComponentBase { }

Describe the solution you'd like

To be able to document the class in the same razor file.

e.g. MyComponent.razor:

<markup>

/// <summary>                      <------------------ THIS
/// Some documentation.
/// </summary>
@class {

  /// <summary>                    <------------------ OR THIS (bool stripped from generated class)
  /// Some documentation.
  /// </summary>
  private bool ___Documentation;

  /// <summary>
  /// Some documentation.
  /// </summary>
  [Parameter] public bool Foo { get; set; }

  //...etc...
}

Applicable Scenarios

Blazor

Describe alternatives you've considered

A separate class. When there are many components, all those .cs files are just noise.

Additional context

No.

[davidcoats]

Adding my vote.

[MarvinKlein1508]

But one cannot document that component itself. So we need this:

MyComponent.razor.cs:

/// <summary>
/// Some documentation.
/// </summary>
public partial class MyComponent : ComponentBase { }

Just a side note, this documentation is not being displayed in the .razor file as well.

/// <summary>
/// Test documentation for the SurveyPrompt component
/// </summary>
public partial class SurveyPrompt

And also not in Intellisense.

[MarvinKlein1508]

Maybe this can be wrapped inside a @documentation or @docs block within the .razor file.

[gulbanana]

I'm definitely suffering from this. Most components I write are a single .razor file, and therefore don't get a doc comment.

[sh-slfcu]

Same boat. So annoying when a codebase is shared among coworkers. How do the official Microsoft components do it?

[davidwengier]

How do the official Microsoft components do it?

Most of the components defined in the runtime are simply defined in a .cs file, and don't use a .razor file: https://github.com/dotnet/aspnetcore/blob/main/src/Components/Authorization/src/AuthorizeView.cs#L9

Alternatively those that do have .razor files would have a partial class in a .cs file and that specifies the documentation comment: https://github.com/dotnet/aspnetcore/blob/main/src/Components/QuickGrid/Microsoft.AspNetCore.Components.QuickGrid/src/QuickGrid.razor.cs#L17

[MarvinKlein1508]

@davidwengier nice addition. When did this get added? This haven't work in the past.

[davidwengier]

I don't know, sorry.

[sh-slfcu]

@davidwengier Thank you for explaining that. Makes sense.

Would be nice to get to where we don't need that extra partial class, but it'll do for me now.

[rob-king-volpara]

Maybe this can be wrapped inside a @documentation or @docs block within the .razor file.

I think this is the cleanest approach in keeping with the how .razor components without code-behind are structured. All that needs to happen is the content of that block in then converted into a /// summary at the top of the generated class.