Skip to content

Fix ///-comments that violate the docs schema #19957

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.

Sign up for GitHub

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

Merged
iSazonov merged 2 commits into from
Jul 13, 2023
Merged

Fix ///-comments that violate the docs schema #19957

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8cefdea
Fix ///-comments that violate the docs schema
sdwheeler Jul 12, 2023
403c41b
Remove duplicate remark
sdwheeler Jul 12, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions ...crosoft.Management.UI.Internal/ManagementList/Common/ReadOnlyObservableAsyncCollection.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,15 +44,15 @@ public ReadOnlyObservableAsyncCollection(IList<T> list)
/// Occurs when the collection changes, either by adding or removing an item.
/// </summary>
/// <remarks>
/// see <seealso cref="INotifyCollectionChanged"/>
/// see <see cref="INotifyCollectionChanged"/>
/// </remarks>
public event NotifyCollectionChangedEventHandler CollectionChanged;

/// <summary>
/// Occurs when a property changes.
/// </summary>
/// <remarks>
/// see <seealso cref="INotifyPropertyChanged"/>
/// see <see cref="INotifyPropertyChanged"/>
/// </remarks>
public event PropertyChangedEventHandler PropertyChanged;
#endregion Events
Expand Down
2 changes: 1 addition & 1 deletion src/Microsoft.Management.UI.Internal/ManagementList/Common/ScalableImage.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ protected override void OnRender(DrawingContext drawingContext)
}

/// <summary>
/// Override of <seealso cref="UIElement.GetLayoutClip"/>.
/// Override of <see cref="UIElement.GetLayoutClip"/>.
/// Make this control to respect the ClipToBounds attribute value.
/// </summary>
/// <param name="layoutSlotSize">An instance of <see cref="System.Windows.Size"/> used for calculating an additional clip.</param>
Expand Down
2 changes: 1 addition & 1 deletion src/Microsoft.Management.UI.Internal/ManagementList/ManagementList/Innerlist.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ public InnerList()

/// <summary>
/// Gets ItemsSource instead.
/// <seealso cref="InnerList"/> Does not support adding to Items.
/// <see cref="InnerList"/> Does not support adding to Items.
/// </summary>
[Browsable(false)]
public new ItemCollection Items
Expand Down
8 changes: 4 additions & 4 deletions src/Microsoft.PowerShell.Commands.Utility/commands/utility/MatchString.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,11 +127,11 @@ public MatchInfo(IReadOnlyList<int> matchIndexes, IReadOnlyList<int> matchLength

/// <summary>
/// Gets the base name of the file containing the matching line.
/// </summary>
/// <remarks>
/// It will be the string "InputStream" if the object came from the input stream.
/// This is a readonly property calculated from the path <see cref="Path"/>.
/// </remarks>
/// </summary>
/// <value>The file name.</value>
public string Filename
{
Expand All @@ -150,10 +150,10 @@ public string Filename

/// <summary>
/// Gets or sets the full path of the file containing the matching line.
/// </summary>
/// <remarks>
/// It will be "InputStream" if the object came from the input stream.
/// </remarks>
/// </summary>
/// <value>The path name.</value>
public string Path
{
Expand Down Expand Up @@ -182,11 +182,11 @@ public string Path

/// <summary>
/// Returns the path of the matching file truncated relative to the <paramref name="directory"/> parameter.
/// </summary>
/// <remarks>
/// For example, if the matching path was c:\foo\bar\baz.c and the directory argument was c:\foo
/// the routine would return bar\baz.c .
/// </remarks>
/// </summary>
/// <param name="directory">The directory base the truncation on.</param>
/// <returns>The relative path that was produced.</returns>
public string RelativePath(string directory)
Expand Down Expand Up @@ -232,12 +232,12 @@ public string RelativePath(string directory)
/// <summary>
/// Returns the string representation of this object. The format
/// depends on whether a path has been set for this object or not.
/// </summary>
/// <remarks>
/// If the path component is set, as would be the case when matching
/// in a file, ToString() would return the path, line number and line text.
/// If path is not set, then just the line text is presented.
/// </remarks>
/// </summary>
/// <returns>The string representation of the match object.</returns>
public override string ToString()
{
Expand Down
12 changes: 6 additions & 6 deletions src/System.Management.Automation/engine/Attributes.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1356,11 +1356,11 @@ public sealed class ValidatePatternAttribute : ValidateEnumeratedArgumentsAttrib
/// Gets or sets the custom error message pattern that is displayed to the user.
/// The text representation of the object being validated and the validating regex is passed as
/// the first and second formatting parameters to the ErrorMessage formatting pattern.
/// <example>
/// <c>
/// <code>
/// [ValidatePattern("\s+", ErrorMessage="The text '{0}' did not pass validation of regex '{1}'")]
/// </code>
/// </example>
/// </c>
/// </summary>
public string ErrorMessage { get; set; }

Expand Down Expand Up @@ -1422,11 +1422,11 @@ public sealed class ValidateScriptAttribute : ValidateEnumeratedArgumentsAttribu
/// Gets or sets the custom error message that is displayed to the user.
/// The item being validated and the validating scriptblock is passed as the first and second
/// formatting argument.
/// <example>
/// <c>
/// <code>
/// [ValidateScript("$_ % 2", ErrorMessage = "The item '{0}' did not pass validation of script '{1}'")]
/// </code>
/// </example>
/// </c>
/// </summary>
public string ErrorMessage { get; set; }

Expand Down Expand Up @@ -1687,11 +1687,11 @@ public sealed class ValidateSetAttribute : ValidateEnumeratedArgumentsAttribute
/// Gets or sets the custom error message that is displayed to the user.
/// The item being validated and a text representation of the validation set is passed as the
/// first and second formatting argument to the <see cref="ErrorMessage"/> formatting pattern.
/// <example>
/// <c>
/// <code>
/// [ValidateSet("A","B","C", ErrorMessage="The item '{0}' is not part of the set '{1}'.")
/// </code>
/// </example>
/// </c>
/// </summary>
public string ErrorMessage { get; set; }

Expand Down
22 changes: 6 additions & 16 deletions src/System.Management.Automation/engine/CommandInfo.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,26 +24,20 @@ public enum CommandTypes
{
/// <summary>
/// Aliases create a name that refers to other command types.
/// </summary>
/// <remarks>
/// Aliases are only persisted within the execution of a single engine.
/// </remarks>
/// </summary>
Alias = 0x0001,

/// <summary>
/// Script functions that are defined by a script block.
/// </summary>
/// <remarks>
/// Functions are only persisted within the execution of a single engine.
/// </remarks>
/// </summary>
Function = 0x0002,

/// <summary>
/// Script filters that are defined by a script block.
/// </summary>
/// <remarks>
/// Filters are only persisted within the execution of a single engine.
/// </remarks>
/// </summary>
Filter = 0x0004,

/// <summary>
Expand All @@ -58,11 +52,9 @@ public enum CommandTypes

/// <summary>
/// Any existing application (can be console or GUI).
/// </summary>
/// <remarks>
/// An application can have any extension that can be executed either directly through CreateProcess
/// or indirectly through ShellExecute.
/// </remarks>
/// </summary>
Application = 0x0020,

/// <summary>
Expand All @@ -77,11 +69,9 @@ public enum CommandTypes

/// <summary>
/// All possible command types.
/// NOTE: a CommandInfo instance will never specify All as its CommandType
/// but All can be used when filtering the CommandTypes.
/// </summary>
/// <remarks>
/// Note, a CommandInfo instance will never specify
/// All as its CommandType but All can be used when filtering the CommandTypes.
/// </remarks>
All = Alias | Function | Filter | Cmdlet | Script | ExternalScript | Application | Configuration,
}

Expand Down
16 changes: 10 additions & 6 deletions src/System.Management.Automation/engine/ErrorPackage.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,13 +28,15 @@ namespace System.Management.Automation
public enum ErrorCategory
{
/// <summary>
/// <para>
/// No error category is specified, or the error category is invalid.
/// </summary>
/// <remarks>
/// </para>
/// <para>
/// Do not specify ErrorCategory.NotSpecified when creating an
/// <see cref="System.Management.Automation.ErrorRecord"/>.
/// Choose the best match from among the other values.
/// </remarks>
/// </para>
/// </summary>
NotSpecified = 0,

/// <summary>
Expand Down Expand Up @@ -132,14 +134,16 @@ public enum ErrorCategory
WriteError = 23,

/// <summary>
/// <para>
/// A native command reported an error to its STDERR pipe.
/// </summary>
/// <remarks>
/// </para>
/// <para>
/// The Engine uses this ErrorCategory when it executes a native
/// console applications and captures the errors reported by the
/// native application. Avoid using ErrorCategory.FromStdErr
/// in other circumstances.
/// </remarks>
/// </para>
/// </summary>
FromStdErr = 24,

/// <summary>
Expand Down
18 changes: 11 additions & 7 deletions src/System.Management.Automation/engine/ProgressRecord.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -505,7 +505,7 @@ internal PSObject ToPSObjectForRemoting()
string activity = string.IsNullOrEmpty(Activity) ? " " : Activity;

PSObject progressAsPSObject = RemotingEncoder.CreateEmptyPSObject();

progressAsPSObject.Properties.Add(new PSNoteProperty(RemoteDataNameStrings.ProgressRecord_Activity, activity));
progressAsPSObject.Properties.Add(new PSNoteProperty(RemoteDataNameStrings.ProgressRecord_ActivityId, this.ActivityId));
progressAsPSObject.Properties.Add(new PSNoteProperty(RemoteDataNameStrings.ProgressRecord_StatusDescription, this.StatusDescription));
Expand All @@ -529,9 +529,10 @@ internal PSObject ToPSObjectForRemoting()
enum ProgressRecordType
{
/// <summary>
/// <para>
/// Operation just started or is not yet complete.
/// </summary>
/// <remarks>
/// </para>
/// <para>
/// A cmdlet can call WriteProgress with ProgressRecordType.Processing
/// as many times as it wishes. However, at the end of the operation,
/// it should call once more with ProgressRecordType.Completed.
Expand All @@ -542,17 +543,20 @@ enum ProgressRecordType
/// of the same Id, the host will update that display.
/// Finally, when the host receives a 'completed' record
/// for that activity, it will remove the progress indicator.
/// </remarks>
/// </para>
/// </summary>
Processing,

/// <summary>
/// <para>
/// Operation is complete.
/// </summary>
/// <remarks>
/// </para>
/// <para>
/// If a cmdlet uses WriteProgress, it should use
/// ProgressRecordType.Completed exactly once, in the last call
/// to WriteProgress.
/// </remarks>
/// </para>
/// </summary>
Completed
}
}
8 changes: 5 additions & 3 deletions src/System.Management.Automation/engine/cmdlet.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1820,14 +1820,16 @@ public enum ShouldProcessReason
None = 0x0,

/// <summary>
/// <para>
/// WhatIf behavior was requested.
/// </summary>
/// <remarks>
/// </para>
/// <para>
/// In the host, WhatIf behavior can be requested explicitly
/// for one cmdlet instance using the -WhatIf commandline parameter,
/// or implicitly for all SupportsShouldProcess cmdlets with $WhatIfPreference.
/// Other hosts may have other ways to request WhatIf behavior.
/// </remarks>
/// </para>
/// </summary>
WhatIf = 0x1,
}
}
4 changes: 2 additions & 2 deletions src/System.Management.Automation/engine/hostifaces/ChoiceDescription.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
namespace System.Management.Automation.Host
{
/// <summary>
/// Provides a description of a choice for use by <seealso cref="System.Management.Automation.Host.PSHostUserInterface.PromptForChoice"/>.
/// Provides a description of a choice for use by <see cref="System.Management.Automation.Host.PSHostUserInterface.PromptForChoice"/>.
/// <!--Used by the engine to describe cmdlet parameters.-->
/// </summary>
public sealed
Expand Down Expand Up @@ -84,7 +84,7 @@ class ChoiceDescription
/// <remarks>
/// Note that the special character &amp; (ampersand) may be embedded in the label string to identify the next character in the label
/// as a "hot key" (aka "keyboard accelerator") that the Console.PromptForChoice implementation may use to allow the user to
/// quickly set input focus to this choice. The implementation of <seealso cref="System.Management.Automation.Host.PSHostUserInterface.PromptForChoice"/>
/// quickly set input focus to this choice. The implementation of <see cref="System.Management.Automation.Host.PSHostUserInterface.PromptForChoice"/>
/// is responsible for parsing the label string for this special character and rendering it accordingly.
///
/// For examples, a choice named "Yes to All" might have "Yes to &amp;All" as it's label.
Expand Down
9 changes: 3 additions & 6 deletions src/System.Management.Automation/engine/hostifaces/Connection.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,7 @@ RunspaceState expectedState
/// The <see cref="StreamingContext"/> that contains contextual information
/// about the source or destination.
/// </param>
[Obsolete("Legacy serialization support is deprecated since .NET 8", DiagnosticId = "SYSLIB0051")]
[Obsolete("Legacy serialization support is deprecated since .NET 8", DiagnosticId = "SYSLIB0051")]
protected InvalidRunspaceStateException(SerializationInfo info, StreamingContext context)
{
throw new NotSupportedException();
Expand Down Expand Up @@ -219,12 +219,9 @@ public enum PSThreadOptions
ReuseThread = 2,

/// <summary>
/// Doesn't create a new thread; the execution occurs on the
/// thread that calls Invoke.
/// Doesn't create a new thread; the execution occurs on the thread
/// that calls Invoke. This option is not valid for asynchronous calls.
/// </summary>
/// <remarks>
/// This option is not valid for asynchronous calls
/// </remarks>
UseCurrentThread = 3
}

Expand Down
12 changes: 6 additions & 6 deletions src/System.Management.Automation/engine/hostifaces/FieldDescription.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -165,7 +165,7 @@ public string Name

/// <summary>
/// A short, human-presentable message to describe and identify the field. If supplied, a typical implementation of
/// <seealso cref="System.Management.Automation.Host.PSHostUserInterface.Prompt"/> will use this value instead of
/// <see cref="System.Management.Automation.Host.PSHostUserInterface.Prompt"/> will use this value instead of
/// the field name to identify the field to the user.
/// </summary>
/// <exception cref="System.Management.Automation.PSArgumentNullException">
Expand All @@ -174,9 +174,9 @@ public string Name
/// <remarks>
/// Note that the special character &amp; (ampersand) may be embedded in the label string to identify the next
/// character in the label as a "hot key" (aka "keyboard accelerator") that the
/// <seealso cref="System.Management.Automation.Host.PSHostUserInterface.Prompt"/> implementation may use
/// <see cref="System.Management.Automation.Host.PSHostUserInterface.Prompt"/> implementation may use
/// to allow the user to quickly set input focus to this field. The implementation of
/// <seealso cref="System.Management.Automation.Host.PSHostUserInterface.Prompt"/> is responsible for parsing
/// <see cref="System.Management.Automation.Host.PSHostUserInterface.Prompt"/> is responsible for parsing
/// the label string for this special character and rendering it accordingly.
///
/// For example, a field named "SSN" might have "&amp;Social Security Number" as it's label.
Expand Down Expand Up @@ -256,12 +256,12 @@ public string Name
}

/// <summary>
/// Gets and sets the default value, if any, for the implementation of <seealso cref="System.Management.Automation.Host.PSHostUserInterface.Prompt"/>
/// Gets and sets the default value, if any, for the implementation of <see cref="System.Management.Automation.Host.PSHostUserInterface.Prompt"/>
/// to pre-populate its UI with. This is a PSObject instance so that the value can be serialized, converted,
/// manipulated like any pipeline object.
/// </summary>
/// <remarks>
/// It is up to the implementer of <seealso cref="System.Management.Automation.Host.PSHostUserInterface.Prompt"/> to decide if it
/// It is up to the implementer of <see cref="System.Management.Automation.Host.PSHostUserInterface.Prompt"/> to decide if it
/// can make use of the object in its presentation of the fields prompt.
///
/// </remarks>
Expand All @@ -283,7 +283,7 @@ public string Name
}

/// <summary>
/// Gets the Attribute classes that apply to the field. In the case that <seealso cref="System.Management.Automation.Host.PSHostUserInterface.Prompt"/>
/// Gets the Attribute classes that apply to the field. In the case that <see cref="System.Management.Automation.Host.PSHostUserInterface.Prompt"/>
/// is being called from the engine, this will contain the set of prompting attributes that are attached to a
/// cmdlet parameter declaration.
/// </summary>
Expand Down
2 changes: 1 addition & 1 deletion src/System.Management.Automation/engine/hostifaces/MshHostRawUserInterface.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1784,7 +1784,7 @@ char source

/// <summary>
/// Creates a 2D array of BufferCells by examining <paramref name="contents"/>.Character.
/// <seealso cref="PSHostRawUserInterface"/>
/// <see cref="PSHostRawUserInterface"/>
/// </summary>
/// <param name="width">
/// The number of columns of the resulting array
Expand Down
Loading