Skip to content

Conversation

Copilot
Copy link
Contributor

@Copilot Copilot AI commented Oct 20, 2025

Summary

Fixed malformed XML documentation in PersistentStateAttribute.RestoreBehavior property that was using incorrect <code cref="..."/> tags instead of the proper <see cref="..."/> syntax.

Problem

The XML documentation was using <code> tags with cref attributes to reference enum values:

/// Use <code cref="RestoreBehavior.SkipInitialValue"/> to skip restoring the initial value

The <code> tag is meant for code samples, not for creating references to types or members. This results in malformed documentation where the cross-references won't work properly in generated documentation or IDE IntelliSense.

Solution

Changed the tags to use <see cref="..."/>, which is the correct XML documentation syntax for creating references:

/// Use <see cref="RestoreBehavior.SkipInitialValue"/> to skip restoring the initial value

This change ensures that:

  • Documentation tools can properly generate hyperlinks to the referenced enum values
  • IDEs can provide proper navigation through IntelliSense
  • The documentation is consistent with the rest of the codebase (e.g., RestoreBehavior.cs already uses <see cref="..."/>)

Changes

  • Updated XML documentation for PersistentStateAttribute.RestoreBehavior property
  • Changed <code cref="RestoreBehavior.SkipInitialValue"/> to <see cref="RestoreBehavior.SkipInitialValue"/>
  • Changed <code cref="RestoreBehavior.SkipLastSnapshot"/> to <see cref="RestoreBehavior.SkipLastSnapshot"/>

Fixes #issue_number

Original prompt

This section details on the original issue you should resolve

<issue_title>XML Documentation for PersistentStateAttribute.RestoreBehavior is malformed.</issue_title>
<issue_description>### Is there an existing issue for this?

  • I have searched the existing issues

Describe the bug

When we look in the source of PersistentStateAttribute we see that it uses <code /> tags to link to a type/value, but that is not the right syntax for XML Documentation.

Expected Behavior

The <code /> tags should be changed to <see /> tags.

/// <remarks>
/// By default it always restores the value on all situations.
-/// Use <code cref="RestoreBehavior.SkipInitialValue"/> to skip restoring the initial value
+/// Use <see cref="RestoreBehavior.SkipInitialValue"/> to skip restoring the initial value
/// when the host starts up.
-/// Use <code cref="RestoreBehavior.SkipLastSnapshot"/> to skip restoring the last value captured
+/// Use <see cref="RestoreBehavior.SkipLastSnapshot"/> to skip restoring the last value captured
/// the last time the current host was shut down.
/// </remarks>

I can submit a PR if you would like.

Steps To Reproduce

No response

Exceptions (if any)

No response

.NET Version

No response

Anything else?

No response</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #64107


✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

Co-authored-by: oroztocil <79744616+oroztocil@users.noreply.github.com>
@Copilot Copilot AI changed the title [WIP] Fix malformed XML documentation for RestoreBehavior Fix malformed XML documentation in PersistentStateAttribute Oct 20, 2025
@Copilot Copilot AI requested a review from oroztocil October 20, 2025 08:16
Copilot finished work on behalf of oroztocil October 20, 2025 08:16
@oroztocil oroztocil marked this pull request as ready for review October 20, 2025 08:18
@oroztocil oroztocil requested a review from a team as a code owner October 20, 2025 08:18
@Copilot Copilot AI review requested due to automatic review settings October 20, 2025 08:18
Copy link
Contributor

@Copilot Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

Fixes malformed XML documentation by replacing incorrect code tags with proper see references for enum values.

  • Replaces with in remarks.
  • Improves IntelliSense and generated docs cross-referencing.

@oroztocil oroztocil enabled auto-merge (squash) October 20, 2025 08:19
@oroztocil
Copy link
Member

/ba-g Unrelated known build error.

@oroztocil oroztocil merged commit d434929 into main Oct 20, 2025
25 of 30 checks passed
@oroztocil oroztocil deleted the copilot/fix-xml-documentation-syntax branch October 20, 2025 09:09
@dotnet-policy-service dotnet-policy-service bot added this to the 11.0-preview1 milestone Oct 20, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

XML Documentation for PersistentStateAttribute.RestoreBehavior is malformed.

3 participants