Regenerated intellisense xml from winforms triple slash comments#5078
Regenerated intellisense xml from winforms triple slash comments#5078AdamYoblick merged 3 commits intodotnet:masterfrom
Conversation
|
I cant seem to add reviewers... @carlossanlop @RussKie @JeremyKuhne Please take a look |
I added you to the list of people with write permissions for this repo, @AdamYoblick. Please accept the invite. Next time you'll be able to add reviewers. |
carlossanlop
left a comment
carlossanlop
left a comment
There was a problem hiding this comment.
Thank you for submitting, @AdamYoblick . I left some suggestions for you to consider.
| <MemberValue>2601</MemberValue> | ||
| <Docs> | ||
| <summary>The font that a glyph is drawn with.</summary> | ||
| <remarks>To be added.</remarks> |
There was a problem hiding this comment.
So this is a tiny bug in the tool, in which if it does not find a <remarks> item in the dotnet-api-docs xml, it will add it with the default boilerplate text.
It's harmless, but if you prefer to remove this (and all other instances) so the PR is smaller, feel free to do it. Totally optional.
I will get it fixed in the tool as soon as I get a chance.
There was a problem hiding this comment.
I see you fixed this in the tool. I'll regenerate these files. :)
There was a problem hiding this comment.
@carlossanlop I used the latest version of the tool, but it seemed to add lots of remarks now regarding explicit interface implementations. Is this intended?
There was a problem hiding this comment.
It wasn't intended but it doesn't hurt.
I just fixed that bug in the newest version. It should not happen again.
| <remarks> | ||
| <format type="text/markdown"><![CDATA[ | ||
|
|
||
| ## Remarks | ||
|
|
||
| Note that for a call to TrackPopupMenu(), a client will see `EVENT_SYSTEM_MENUSTART` followed almost immediately by `EVENT_SYSTEM_MENUPOPUPSTART` for the popup being shown. | ||
|
|
||
| ]]></format> | ||
| </remarks> |
There was a problem hiding this comment.
Is this a remark only relevant for developers reading the source code? TrackPopupMenu() seems to be a Windows method, that's why I ask.
If you think that is the case, we can remove it:
| <remarks> | |
| <format type="text/markdown"><![CDATA[ | |
| ## Remarks | |
| Note that for a call to TrackPopupMenu(), a client will see `EVENT_SYSTEM_MENUSTART` followed almost immediately by `EVENT_SYSTEM_MENUPOPUPSTART` for the popup being shown. | |
| ]]></format> | |
| </remarks> | |
| <remarks>To be added.</remarks> |
There was a problem hiding this comment.
@RussKie You added this comment a while back, should we leave it as is?
| <remarks> | ||
| <format type="text/markdown"><![CDATA[ | ||
|
|
||
| ## Remarks | ||
|
|
||
| Note that for a call to TrackPopupMenu(), a client will see `EVENT_SYSTEM_MENUSTART` followed almost immediately by `EVENT_SYSTEM_MENUPOPUPSTART` for the popup being shown. | ||
|
|
||
| ]]></format> | ||
| </remarks> |
There was a problem hiding this comment.
Same. Feel free to apply the suggestion if this is not something that matters to people reading the API description in MS Docs:
| <remarks> | |
| <format type="text/markdown"><![CDATA[ | |
| ## Remarks | |
| Note that for a call to TrackPopupMenu(), a client will see `EVENT_SYSTEM_MENUSTART` followed almost immediately by `EVENT_SYSTEM_MENUPOPUPSTART` for the popup being shown. | |
| ]]></format> | |
| </remarks> | |
| <remarks>To be added.</remarks> |
|
|
||
| ## Remarks | ||
|
|
||
| This method is obsolete and unused. |
There was a problem hiding this comment.
Here and elsewhere - Since the <remarks> information does not show up in Intellisense in Visual Studio, I think we should move this text to the <summary>, although I am not sure what is the best guidance for mentioning obsoletion. What would you suggest, @gewarren?
There was a problem hiding this comment.
I added a suggestion in the summary. If this method was decorated with [ObsoleteAttribute] it would automatically show as obsolete in the docs, but I'm not sure how that manifests in IntelliSense.
There was a problem hiding this comment.
@RussKie There are several methods in BindingContext.cs that are called out as obsolete in the remarks. Should we decorate them with [Obsolete] so the docs get generated correctly?
| <remarks>To be added.</remarks> | ||
| <exception cref="T:System.ArgumentNullException"> | ||
| <paramref name="dc" /> is <see langword="null" />.</exception> | ||
| <exception cref="T:System.ArgumentOutOfRangeException">Thrown if <see cref="F:System.Windows.Forms.TextFormatFlags.ModifyString" /> is set.</exception> |
There was a problem hiding this comment.
| <exception cref="T:System.ArgumentOutOfRangeException">Thrown if <see cref="F:System.Windows.Forms.TextFormatFlags.ModifyString" /> is set.</exception> | |
| <exception cref="T:System.ArgumentOutOfRangeException"><see cref="F:System.Windows.Forms.TextFormatFlags.ModifyString" /> is set.</exception> |
| <param name="text">The text to measure.</param> | ||
| <param name="font">The <see cref="T:System.Drawing.Font" /> to apply to the measured text.</param> | ||
| <summary>Provides the size, in pixels, of the specified text when drawn with the specified font.</summary> | ||
| <returns>The <see cref="T:System.Drawing.Size" />, in pixels, of text drawn on a single line with the specified font. You can manipulate how the text is drawn by using one of the <see cref="M:System.Windows.Forms.TextRenderer.DrawText(System.Drawing.IDeviceContext,System.ReadOnlySpan{System.Char},System.Drawing.Font,System.Drawing.Rectangle,System.Drawing.Color,System.Windows.Forms.TextFormatFlags)" /> overloads that takes a <see cref="T:System.Windows.Forms.TextFormatFlags" /> parameter. For example, the default behavior of the <see cref="T:System.Windows.Forms.TextRenderer" /> is to add padding to the bounding rectangle of the drawn text to accommodate overhanging glyphs. If you need to draw a line of text without these extra spaces you should use the versions of <see cref="M:System.Windows.Forms.TextRenderer.DrawText(System.Drawing.IDeviceContext,System.ReadOnlySpan{System.Char},System.Drawing.Font,System.Drawing.Point,System.Drawing.Color)" /> and <see cref="M:System.Windows.Forms.TextRenderer.MeasureText(System.Drawing.IDeviceContext,System.ReadOnlySpan{System.Char},System.Drawing.Font)" /> that take a Size and <see cref="T:System.Windows.Forms.TextFormatFlags" /> parameter. For an example, see <see cref="M:System.Windows.Forms.TextRenderer.MeasureText(System.Drawing.IDeviceContext,System.String,System.Drawing.Font,System.Drawing.Size,System.Windows.Forms.TextFormatFlags)" />.</returns> |
There was a problem hiding this comment.
Maybe some of this information could be moved to the remarks. We probably don't need all this information to be clustered in the return value, we only need the essential description.
| <summary>Provides the size, in pixels, of the specified text when drawn with the specified font and formatting instructions, using the specified size to create the initial bounding rectangle for the text.</summary> | ||
| <returns>The <see cref="T:System.Drawing.Size" />, in pixels, of <paramref name="text" /> drawn with the specified <paramref name="font" /> and format.</returns> | ||
| <remarks>To be added.</remarks> | ||
| <exception cref="T:System.ArgumentOutOfRangeException">Thrown if <see cref="F:System.Windows.Forms.TextFormatFlags.ModifyString" /> is set.</exception> |
There was a problem hiding this comment.
| <exception cref="T:System.ArgumentOutOfRangeException">Thrown if <see cref="F:System.Windows.Forms.TextFormatFlags.ModifyString" /> is set.</exception> | |
| <exception cref="T:System.ArgumentOutOfRangeException"><see cref="F:System.Windows.Forms.TextFormatFlags.ModifyString" /> is set.</exception> |
| <remarks>To be added.</remarks> | ||
| <exception cref="T:System.ArgumentNullException"> | ||
| <paramref name="dc" /> is <see langword="null" />.</exception> | ||
| <exception cref="T:System.ArgumentOutOfRangeException">Thrown if <see cref="F:System.Windows.Forms.TextFormatFlags.ModifyString" /> is set.</exception> |
There was a problem hiding this comment.
| <exception cref="T:System.ArgumentOutOfRangeException">Thrown if <see cref="F:System.Windows.Forms.TextFormatFlags.ModifyString" /> is set.</exception> | |
| <exception cref="T:System.ArgumentOutOfRangeException"><see cref="F:System.Windows.Forms.TextFormatFlags.ModifyString" /> is set.</exception> |
|
|
||
| ## Remarks | ||
|
|
||
| Certain messages are forwarder directly to the ActiveX control, others are first processed by the wndproc of Control |
There was a problem hiding this comment.
Is this information that the average MS Docs user would be interested in, or is this aimed to the maintainers of the source code?
| Certain messages are forwarder directly to the ActiveX control, others are first processed by the wndproc of Control | |
| Certain messages are forwarder directly to the ActiveX control, others are first processed by the wndproc of Control. |
| @@ -204,7 +204,15 @@ this->BindingContext->get_Item(dataSet1->Customers)->Position = 1; | |||
| <param name="dataSource">The <see cref="T:System.Object" /> associated with the <see cref="T:System.Windows.Forms.BindingManagerBase" />.</param> | |||
| <param name="listManager">The <see cref="T:System.Windows.Forms.BindingManagerBase" /> to add.</param> | |||
| <summary>Adds the <see cref="T:System.Windows.Forms.BindingManagerBase" /> associated with a specific data source to the collection.</summary> | |||
There was a problem hiding this comment.
| <summary>Adds the <see cref="T:System.Windows.Forms.BindingManagerBase" /> associated with a specific data source to the collection.</summary> | |
| <summary>This method is obsolete. Adds the <see cref="T:System.Windows.Forms.BindingManagerBase" /> associated with a specific data source to the collection.</summary> |
There was a problem hiding this comment.
@carlossanlop @gewarren I have a question about the tool that ports triple slash comments to the doc xml. I'm looking at our BindingContext.cs and I see this for the summary:
/// <summary>
/// Adds the listManager to the collection. An ArgumentNullException is thrown if this
/// listManager is null. An exception is thrown if a listManager to the same target
/// and Property as an existing listManager or if the listManager's column isn't a
/// valid column given this DataSource.Table's schema.
/// Fires the CollectionChangedEvent.
/// </summary>
But in BindingContext.xml, the summary does not match the code. Did I miss a flag on the command line or something?
|
|
||
| ## Remarks | ||
|
|
||
| This method is obsolete and unused. |
There was a problem hiding this comment.
I added a suggestion in the summary. If this method was decorated with [ObsoleteAttribute] it would automatically show as obsolete in the docs, but I'm not sure how that manifests in IntelliSense.
| <returns>To be added.</returns> | ||
| <remarks>To be added.</remarks> | ||
| <summary>Returns the handle to a Windows device context.</summary> | ||
| <returns>An <see cref="T:System.IntPtr" /> representing the handle of a device context.</returns> |
There was a problem hiding this comment.
| <returns>An <see cref="T:System.IntPtr" /> representing the handle of a device context.</returns> | |
| <returns>The handle of a device context.</returns> |
The type shouldn't be explicitly stated since it's shown automatically in docs (and IntelliSense I believe).
There was a problem hiding this comment.
@carlossanlop This also doesn't match what's in our code. The GetHdc() method in DrawItemEventArgs.cs has literally no XML docs, so the tool should have cleared these out?
| <Docs> | ||
| <param name="e">To be added.</param> | ||
| <summary>To be added.</summary> | ||
| <summary>Fires the <see cref="E:System.Windows.Forms.ListView.GroupCollapsedStateChanged" /> event.</summary> |
There was a problem hiding this comment.
| <summary>Fires the <see cref="E:System.Windows.Forms.ListView.GroupCollapsedStateChanged" /> event.</summary> | |
| <summary>Raises the <see cref="E:System.Windows.Forms.ListView.GroupCollapsedStateChanged" /> event.</summary> |
See https://github.com/dotnet/dotnet-api-docs/wiki/Summary%3A-Event-related.
| <Docs> | ||
| <param name="e">To be added.</param> | ||
| <summary>To be added.</summary> | ||
| <summary>Fires the <see cref="E:System.Windows.Forms.ListView.GroupTaskLinkClick" /> event.</summary> |
There was a problem hiding this comment.
| <summary>Fires the <see cref="E:System.Windows.Forms.ListView.GroupTaskLinkClick" /> event.</summary> | |
| <summary>Raises the <see cref="E:System.Windows.Forms.ListView.GroupTaskLinkClick" /> event.</summary> |
| <param name="dc">The device context in which to draw the text.</param> | ||
| <param name="text">The text to draw.</param> | ||
| <param name="font">The <see cref="T:System.Drawing.Font" /> to apply to the drawn text.</param> | ||
| <param name="pt">The <see cref="T:System.Drawing.Point" /> that represents the upper-left corner of the drawn text.</param> |
There was a problem hiding this comment.
| <param name="pt">The <see cref="T:System.Drawing.Point" /> that represents the upper-left corner of the drawn text.</param> | |
| <param name="pt">The point that represents the upper-left corner of the drawn text.</param> |
| <param name="text">The text to draw.</param> | ||
| <param name="font">The <see cref="T:System.Drawing.Font" /> to apply to the drawn text.</param> | ||
| <param name="pt">The <see cref="T:System.Drawing.Point" /> that represents the upper-left corner of the drawn text.</param> | ||
| <param name="foreColor">The <see cref="T:System.Drawing.Color" /> to apply to the drawn text.</param> |
There was a problem hiding this comment.
| <param name="foreColor">The <see cref="T:System.Drawing.Color" /> to apply to the drawn text.</param> | |
| <param name="foreColor">The color to apply to the drawn text.</param> |
| <param name="text">The text to measure.</param> | ||
| <param name="font">The <see cref="T:System.Drawing.Font" /> to apply to the measured text.</param> | ||
| <summary>Provides the size, in pixels, of the specified text when drawn with the specified font.</summary> | ||
| <returns>The <see cref="T:System.Drawing.Size" />, in pixels, of text drawn on a single line with the specified font. You can manipulate how the text is drawn by using one of the <see cref="M:System.Windows.Forms.TextRenderer.DrawText(System.Drawing.IDeviceContext,System.ReadOnlySpan{System.Char},System.Drawing.Font,System.Drawing.Rectangle,System.Drawing.Color,System.Windows.Forms.TextFormatFlags)" /> overloads that takes a <see cref="T:System.Windows.Forms.TextFormatFlags" /> parameter. For example, the default behavior of the <see cref="T:System.Windows.Forms.TextRenderer" /> is to add padding to the bounding rectangle of the drawn text to accommodate overhanging glyphs. If you need to draw a line of text without these extra spaces you should use the versions of <see cref="M:System.Windows.Forms.TextRenderer.DrawText(System.Drawing.IDeviceContext,System.ReadOnlySpan{System.Char},System.Drawing.Font,System.Drawing.Point,System.Drawing.Color)" /> and <see cref="M:System.Windows.Forms.TextRenderer.MeasureText(System.Drawing.IDeviceContext,System.ReadOnlySpan{System.Char},System.Drawing.Font)" /> that take a Size and <see cref="T:System.Windows.Forms.TextFormatFlags" /> parameter. For an example, see <see cref="M:System.Windows.Forms.TextRenderer.MeasureText(System.Drawing.IDeviceContext,System.String,System.Drawing.Font,System.Drawing.Size,System.Windows.Forms.TextFormatFlags)" />.</returns> |
There was a problem hiding this comment.
| <returns>The <see cref="T:System.Drawing.Size" />, in pixels, of text drawn on a single line with the specified font. You can manipulate how the text is drawn by using one of the <see cref="M:System.Windows.Forms.TextRenderer.DrawText(System.Drawing.IDeviceContext,System.ReadOnlySpan{System.Char},System.Drawing.Font,System.Drawing.Rectangle,System.Drawing.Color,System.Windows.Forms.TextFormatFlags)" /> overloads that takes a <see cref="T:System.Windows.Forms.TextFormatFlags" /> parameter. For example, the default behavior of the <see cref="T:System.Windows.Forms.TextRenderer" /> is to add padding to the bounding rectangle of the drawn text to accommodate overhanging glyphs. If you need to draw a line of text without these extra spaces you should use the versions of <see cref="M:System.Windows.Forms.TextRenderer.DrawText(System.Drawing.IDeviceContext,System.ReadOnlySpan{System.Char},System.Drawing.Font,System.Drawing.Point,System.Drawing.Color)" /> and <see cref="M:System.Windows.Forms.TextRenderer.MeasureText(System.Drawing.IDeviceContext,System.ReadOnlySpan{System.Char},System.Drawing.Font)" /> that take a Size and <see cref="T:System.Windows.Forms.TextFormatFlags" /> parameter. For an example, see <see cref="M:System.Windows.Forms.TextRenderer.MeasureText(System.Drawing.IDeviceContext,System.String,System.Drawing.Font,System.Drawing.Size,System.Windows.Forms.TextFormatFlags)" />.</returns> | |
| <returns>The size, in pixels, of text drawn on a single line with the specified font.</returns> |
| <summary>To be added.</summary> | ||
| <returns>To be added.</returns> | ||
| <summary>Provides the size, in pixels, of the specified text drawn with the specified font in the specified device context.</summary> | ||
| <returns>The <see cref="T:System.Drawing.Size" />, in pixels, of <paramref name="text" /> drawn with the specified <paramref name="font" /> in the specified device context.</returns> |
There was a problem hiding this comment.
| <returns>The <see cref="T:System.Drawing.Size" />, in pixels, of <paramref name="text" /> drawn with the specified <paramref name="font" /> in the specified device context.</returns> | |
| <returns>The size, in pixels, of <paramref name="text" /> drawn with the specified <paramref name="font" /> in the specified device context.</returns> |
| <param name="text">The text to measure.</param> | ||
| <param name="font">The <see cref="T:System.Drawing.Font" /> to apply to the measured text.</param> | ||
| <param name="proposedSize">The <see cref="T:System.Drawing.Size" /> of the initial bounding rectangle.</param> | ||
| <param name="flags">The formatting instructions to apply to the measured text.</param> |
There was a problem hiding this comment.
| <param name="flags">The formatting instructions to apply to the measured text.</param> | |
| <param name="flags">A bitwise combination of the enumeration values that specifies the formatting instructions to apply to the measured text.</param> |
|
Docs Build status updates of commit 36b9b58: ✅ Validation status: passed
For more details, please refer to the build report. Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report. For any questions, please:
|
|
I'm not going to lie, this task blew up in scope. I just wanted to make sure the intellisense docs were up to date since we have a bunch of debt in this area (i.e. completely missing API). I think we should make a separate task to "fix up" comments where appropriate. Issue tracking the fix up is at dotnet/winforms#4194 @carlossanlop @gewarren Thank you for the very good feedback, I'm not ignoring it by any means, I just have other tasks to work on and I think we can do this in stages. |
7 participants
Fixes dotnet/winforms#4163
I followed the steps described at https://github.com/carlossanlop/DocsPortingTool.
The command line I ran was
.\DocsPortingTool\bin\Debug\net5.0\DocsPortingTool.exe -Docs E:\src\repos\github\dotnet-api-docs\xml -TripleSlash E:\src\repos\github\winforms\artifacts\bin -IncludedAssemblies Accessibility,Microsoft.VisualBasic.Forms,System.Windows.Forms.Design,System.Windows.Forms.Primitives,System.Windows.Forms -Save truePlease let me know if you have any concerns 😄