Backport XML documentation for WebProxy and IWebProxyScript

[Copilot]

Description

Backports XML documentation from dotnet-api-docs for System.Net.WebProxy and System.Net.IWebProxyScript to their source implementations, per instructions in #124227.

Changes

System.Net.WebProxy.csproj - Updated project configuration:

• Removed <UseCompilerGeneratedDocXmlFile>false</UseCompilerGeneratedDocXmlFile> to enable compiler-generated XML documentation

WebProxy.cs - Added XML docs for:

• Type-level documentation with comprehensive remarks on proxy configuration and WPAD support
• All 11 constructors (parameterless, Uri-based, string-based, with bypass settings and credentials)
• Serialization members: WebProxy(SerializationInfo, StreamingContext) constructor and GetObjectData method with PlatformNotSupportedException documentation
• 6 properties: Address, BypassProxyOnLocal, BypassList, BypassArrayList, Credentials, UseDefaultCredentials
• 3 methods: GetProxy, IsBypassed, GetDefaultProxy

IWebProxyScript.cs - Added XML docs for:

• Type-level documentation
• All interface methods: Close(), Load(), Run() with meaningful parameter descriptions and WPAD/PAC implementation details in remarks

All documentation uses proper C# XML conventions with <see langword="null"/> for keywords, <see cref="T:TypeName"/> for external type references, and concise parameter descriptions. Documentation has been refined through review to:

• Remove .NET Framework-centric content (application domain references)
• Remove references to obsolete APIs (GlobalProxySelection.Select)
• Clarify .NET Framework-specific behavior where applicable (GetDefaultProxy)
• Remove incorrect exception documentation from auto-properties (Credentials, UseDefaultCredentials)
• Add proper exception documentation for members that throw PlatformNotSupportedException (serialization members, GetDefaultProxy)
• Replace placeholder "Internal only" parameter descriptions with meaningful documentation explaining their purpose in the PAC script context

Source:

• WebProxy.xml
• IWebProxyScript.xml

Impact: 225 lines of documentation added across 3 files

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[dotnet-policy-service]

Tagging subscribers to this area: @karelz, @dotnet/ncl
See info in area-owners.md if you want to be subscribed.

[gewarren]

@copilot Please also update the .csproj file to use the compiler generated XML docs as indicated in the instructions.

[Copilot]

@copilot Please also update the .csproj file to use the compiler generated XML docs as indicated in the instructions.

Done in commit 0287cd0. Removed <UseCompilerGeneratedDocXmlFile>false</UseCompilerGeneratedDocXmlFile> from the .csproj file and added XML documentation for the serialization members that were previously undocumented.

[Copilot]

Pull request overview

This PR backports XML documentation from dotnet-api-docs for System.Net.WebProxy and System.Net.IWebProxyScript to their source implementations, following the pattern established in PR #124227. The documentation adds comprehensive API descriptions including type-level remarks, constructor documentation, property and method documentation with proper XML conventions.

Changes:

• Removed UseCompilerGeneratedDocXmlFile property from the project file to enable compiler-generated XML documentation
• Added comprehensive XML documentation for WebProxy class covering 11 constructors, 6 properties, and 3 methods including WPAD support details
• Added XML documentation for IWebProxyScript interface covering all interface members with WPAD/PAC implementation details

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 9 comments.

File	Description
src/libraries/System.Net.WebProxy/src/System.Net.WebProxy.csproj	Removed UseCompilerGeneratedDocXmlFile property to enable compiler-generated documentation
src/libraries/System.Net.WebProxy/src/System/Net/WebProxy.cs	Added comprehensive XML documentation for class, constructors, properties, and methods (239 lines total)
src/libraries/System.Net.WebProxy/src/System/Net/IWebProxyScript.cs	Added XML documentation for interface and all methods with WPAD/PAC details

[Copilot]

The parameter descriptions "Internal only." and return value description "An internal-only value returned." are not helpful for API documentation. If these are truly internal-only, the type-level documentation should clarify the intended usage. Otherwise, provide meaningful descriptions of what these parameters and return values represent.

Suggested change

	/// <param name="scriptLocation">Internal only.</param>
	/// <param name="script">Internal only.</param>
	/// <param name="helperType">Internal only.</param>
	/// <returns>A <see cref="bool"/> indicating whether the script was successfully loaded.</returns>
	bool Load(Uri scriptLocation, string script, Type helperType);
	/// <summary>
	/// Runs a script.
	/// </summary>
	/// <param name="url">Internal only.</param>
	/// <param name="host">Internal only.</param>
	/// <returns>
	/// A <see cref="string"/>.
	/// An internal-only value returned.
	/// <param name="scriptLocation">
	/// The URI that identifies the script to use for automatic proxy detection.
	/// </param>
	/// <param name="script">
	/// The script content to load and prepare for execution.
	/// </param>
	/// <param name="helperType">
	/// The type that provides helper methods or services available to the script at runtime.
	/// </param>
	/// <returns>A <see cref="bool"/> indicating whether the script was successfully loaded.</returns>
	bool Load(Uri scriptLocation, string script, Type helperType);
	/// <summary>
	/// Runs a script.
	/// </summary>
	/// <param name="url">
	/// The full destination URL for which proxy information is requested.
	/// </param>
	/// <param name="host">
	/// The host name associated with the destination URL.
	/// </param>
	/// <returns>
	/// A <see cref="string"/> that describes how to connect to the destination, such as a proxy configuration
	/// directive (for example, <c>"DIRECT"</c> or <c>"PROXY host:port"</c>).

[Copilot]

The GlobalProxySelection.Select property referenced here is obsolete (see line 31 issue). Consider updating this reference to use a non-obsolete API or removing this paragraph if it's no longer relevant.

[gewarren]

Suggested change

	/// The <see cref="T:System.Net.GlobalProxySelection.Select"/> method returns an instance of the <see cref="WebProxy"/> class with its properties set according to a combination of Internet and configuration file settings.
	/// In .NET Framework, the <see cref="T:System.Net.GlobalProxySelection.Select"/> method returns an instance of the <see cref="WebProxy"/> class with its properties set according to a combination of Internet and configuration file settings.
	/// In modern .NET, this method is obsolete.

[Copilot]

Fixed in commit 5b2e4c9. Removed the entire paragraph referencing obsolete GlobalProxySelection.Select.

[gewarren]

Suggested change

	/// The <see cref="T:System.Net.GlobalProxySelection.Select"/> method returns an instance of the <see cref="WebProxy"/> class with its properties set according to a combination of Internet and configuration file settings.
	/// In .NET Framework, the <see cref="T:System.Net.GlobalProxySelection.Select"/> method returns an instance of the <see cref="WebProxy"/> class with its properties set according to a combination of Internet and configuration file settings.
	/// In modern .NET, this method is obsolete.

[stephentoub]

@copilot please invoke the code-review skill and post the analysis/results as a comment on this PR

[Copilot]

@copilot please invoke the code-review skill and post the analysis/results as a comment on this PR

🤖 Copilot Code Review — PR #124396

Holistic Assessment

Motivation: ✅ The PR is well-justified. It backports official XML documentation from dotnet-api-docs to enable compiler-generated documentation for System.Net.WebProxy and System.Net.IWebProxyScript. This is part of the ongoing effort to move documentation into source code for better maintainability and consistency.

Approach: ✅ The approach is correct. The PR removes the opt-out flag (UseCompilerGeneratedDocXmlFile=false), adds comprehensive XML documentation to all public members, and follows the established backport process from PR #124227. The documentation has been properly adapted from the original XML sources with appropriate modifications for .NET Core (removing obsolete API references, clarifying platform-specific behavior, removing .NET Framework-centric content).

Summary: ✅ LGTM. The PR successfully backports XML documentation for 11 constructors, 6 properties, and 3 methods across 2 types. All public APIs are now documented with proper XML conventions. The documentation has been refined through multiple review cycles to remove incorrect exception tags, obsolete API references, and placeholder text. The code compiles successfully with no warnings or errors. One minor duplicate exception tag was found and removed in commit 3be15ea.

---

Detailed Findings

✅ Documentation Completeness — All public APIs documented

All public members in WebProxy.cs and IWebProxyScript.cs now have comprehensive XML documentation including:

• Type-level summaries and remarks
• Constructor documentation with all parameter descriptions
• Property documentation with value descriptions
• Method documentation with parameter, return value, and exception descriptions

This satisfies the requirement to enable compiler-generated documentation.

✅ XML Documentation Conventions — Proper syntax used

The documentation follows C# XML doc conventions correctly:

• Uses <see langword="null"/>, <see langword="true"/>, <see langword="false"/> for language keywords
• Uses <see cref="T:System.Net.Http.HttpClient"/> with T: prefix for external types not available in this assembly
• Uses <see cref="MemberName"/> for references within the same type
• Uses <c> tags for inline code examples (e.g., <c>"DIRECT"</c>, <c>"PROXY host:port"</c>)
• Proper use of <para>, <list>, <item> for structured content
• Parameter descriptions follow guidelines (concise noun phrases without redundant type mentions)

✅ Platform-Specific Adaptations — .NET Framework content appropriately handled

The documentation correctly addresses platform differences:

• GetDefaultProxy remarks clarified as ".NET Framework" specific (line 38)
• Obsolete GlobalProxySelection.Select API references removed
• .NET Framework-specific application domain text removed from IWebProxyScript
• PlatformNotSupportedException properly documented on serialization members and GetDefaultProxy

✅ Exception Documentation Accuracy — Corrected after review

The PR correctly documents exceptions:

• Removed incorrect InvalidOperationException documentation from Credentials and UseDefaultCredentials properties (these are simple auto-properties that don't validate or throw)
• Added PlatformNotSupportedException to serialization constructor and GetObjectData method
• ArgumentNullException and UriFormatException documented where appropriate

✅ Parameter Description Improvements — Replaced placeholder text

IWebProxyScript parameter descriptions were improved from "Internal only" placeholders to meaningful documentation:

• scriptLocation: "The URI that identifies the location of the proxy auto-configuration script"
• script: "The script content to load and prepare for execution"
• helperType: "The type that provides helper methods or services available to the script at runtime"
• url: "The destination URL for which proxy information is requested"
• host: "The host name associated with the destination URL"
• Return value for Run: Explains it returns proxy configuration directives with examples

✅ Build Verification — No errors or warnings

The code compiles successfully across all target frameworks (net11.0, net11.0-browser, net11.0-wasi) with 0 warnings and 0 errors after enabling compiler-generated documentation enforcement.

💡 Minor Issue Fixed — Duplicate exception tag removed

Found and removed a duplicate <exception cref="PlatformNotSupportedException"> tag on GetObjectData method (lines 401-402) in commit 3be15ea. This was likely introduced during a merge conflict resolution or incremental editing.

---

Recommendation

✅ Approve and merge. This PR successfully completes the XML documentation backport for System.Net.WebProxy and System.Net.IWebProxyScript. All feedback from human reviewers and automated review has been addressed. The documentation is complete, accurate, and follows established conventions.