Code documentation comments for ASP.NET razor pages?

Question

Is it possible to add code documentation comments to razor pages (resp.: components)?

I found it possible to use standard documentation comments for page parameters (which are declared in @code blocks), but I am still looking for a way to add comments for the component (class) itself.

For parameters, this works:

@code
{
   /// <summary> The Id of the selected account. </summary>
   [Parameter]
   public int SelectedAccount { get; set; }
}

So, for a class, it should be something like this:

@***
    <summary> This component renders a table. </summary>
***@

or

@classcomment{
    <summary> This component renders a table. </summary>
}

Does anyone know a way?

Answer 1

I don't think this is possible just from .razor files. However, you can add a "code-behind" file where you could place the documentation (this is not ideal, of course, because the documentation is separate from the Razor code).

For example, let this be your Component.razor:

<p>Some component</p>

@code
{
   /// <summary> The Id of the selected account. </summary>
   [Parameter]
   public int SelectedAccount { get; set; }
}

You can create Component.razor.cs with the component's documentation comment (the filename is not important, but it's a nice convention to follow this scheme):

/// <summary> This component renders a table. </summary>
partial class Component { }

Note that the namespaces must match (in this example I haven't used any, but you could specify namespace via @namespace directive in the .razor file or folder structure, and namespace block in the .cs file as usual).

Answer 2

The simple answer is "it cannot be done", for now.

I've opened a feature request on the razor repo. If you want this feature, please upvote it!

Until this is possible, the accepted answer is a very nice workaround (but requires an extra file, which is a nuisance).