WIP: Update WinForms docs #2974

RussKie · 2019-08-09T15:39:41Z

Summary

Update WinForms API from xml-docs by running DocsPortingTool.

xml/System.Windows.Forms.Design.Behavior/BehaviorServiceAdornerCollection.xml

mairaw · 2019-08-12T19:00:09Z

@carlossanlop I'm breaking this PR apart to make it easier for us to review and merge. My new PRs will already have the needed edits in place.

mairaw · 2019-08-14T06:15:46Z

xml/System.Windows.Forms/AccessibleEvents.xml

@@ -616,6 +616,12 @@
      <MemberValue>15</MemberValue>
      <Docs>
        <summary>An application is about to exit drag-and-drop mode. Applications that support drag-and-drop operations must send this event; the system does not.</summary>
+        <remarks>


@RussKie are these remarks information that is important to customer to know? If so, we need to move them to a different place because enum fields don't have remarks on docs
https://docs.microsoft.com/en-us/dotnet/api/system.windows.forms.accessibleevents?view=netcore-3.0

Just let me know so I can work on the PR if needed.

Agree. I converted these remarks into comments.
Please remove.

mairaw · 2019-08-14T06:47:41Z

xml/System.Windows.Forms/BindingContext.xml

-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+This method is obsolete and unused.


These APIs are obsolete but they don't have an obsolete attribute?

Also, obsolete only in .NET Core? We'd need to tell since when because the docs are for all versions.

Good spot! Looks like these comments come all the way from NETFx, e.g.
http://index/?query=bindingcontext&rightProject=System.Windows.Forms&file=System%5CWinForms%5CBindingContext.cs&line=158

@merriemcgaw @Tanya-Solyanik should we decorate these methods as oboslete (with warning)?

mairaw · 2019-08-14T07:24:17Z

xml/System.Windows.Forms/GridItem.xml

-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+We don't do set because of the value class semantics, etc.


seems like an internal comment. Do we need this?

Please remove

RussKie · 2019-08-14T10:02:52Z

xml/System.Windows.Forms.Design/DesignerActionListsChangedEventArgs.xml

@@ -39,7 +39,7 @@
        <param name="relatedObject">To be added.</param>
        <param name="changeType">To be added.</param>
        <param name="actionLists">To be added.</param>
-        <summary>To be added.</summary>
+        <summary>Constructor that requires the object in question, the type of change and the remaining actionlists left for the object. on the related object.</summary>


Suggested change

<summary>Constructor that requires the object in question, the type of change and the remaining actionlists left for the object. on the related object.</summary>

<summary>Constructor that requires the object in question, the type of change and the remaining actionlists left for the object on the related object.</summary>

RussKie · 2019-08-14T10:11:29Z

xml/System.Windows.Forms.Design/DesignerActionListsChangedEventArgs.xml

@@ -14,7 +14,7 @@
  </Base>
  <Interfaces />
  <Docs>
-    <summary>To be added.</summary>
+    <summary>This EventArgs class is used by the DesignerActionService to signify that there has been a change in DesignerActionLists (added or removed) on the related object.</summary>


I'm a bit unsure about the syntax, but I think the following is a little more meaningful:

Suggested change

<summary>This EventArgs class is used by the DesignerActionService to signify that there has been a change in DesignerActionLists (added or removed) on the related object.</summary>

<summary>This class is used by the <see cref="DesignerActionService"/> to signify that there has been a change in the <see cref="DesignerActionListCollection">designer action lists collection</see> (added or removed) on the related object.</summary>

I'm updating our xml-docs to read the above.

RussKie · 2019-08-14T10:12:40Z

xml/System.Windows.Forms.Design/DesignerActionListsChangedEventArgs.xml

@@ -80,7 +80,7 @@
        <ReturnType>System.Windows.Forms.Design.DesignerActionListsChangedType</ReturnType>
      </ReturnValue>
      <Docs>
-        <summary>To be added.</summary>
+        <summary>The type of changed that caused the related event to be thrown.</summary>


Suggested change

<summary>The type of changed that caused the related event to be thrown.</summary>

<summary>The type of change that caused the related event to be thrown.</summary>

The xml-docs updated

RussKie · 2019-08-14T10:14:01Z

xml/System.Windows.Forms.Design/DesignerActionListsChangedType.xml

@@ -18,7 +18,7 @@
    </Attribute>
  </Attributes>
  <Docs>
-    <summary>To be added.</summary>
+    <summary>An enum that defines what time of action happend to the  related object's DesignerActionLists collection.</summary>


Suggested change

<summary>An enum that defines what time of action happend to the related object's DesignerActionLists collection.</summary>

<summary>An enum that defines what type of action happend to the related object's <see cref="DesignerActionListCollection">designer action lists collection</see>.</summary>

The xml-doc is updated

RussKie · 2019-08-14T10:15:12Z

xml/System.Windows.Forms.Design/DesignerActionUIService.xml

@@ -38,7 +38,7 @@
        <ReturnType>System.ComponentModel.Design.DesignerActionUIStateChangeEventHandler</ReturnType>
      </ReturnValue>
      <Docs>
-        <summary>To be added.</summary>
+        <summary>This event is thrown whenever a request is made to show/hide the ui</summary>


Suggested change

<summary>This event is thrown whenever a request is made to show/hide the ui</summary>

<summary>This event is thrown whenever a request is made to show/hide the UI.</summary>

The xml-doc is updated

RussKie · 2019-08-14T10:36:41Z

xml/System.Windows.Forms/FolderBrowserDialog.xml

@@ -124,7 +124,7 @@
        <ReturnType>System.Boolean</ReturnType>
      </ReturnValue>
      <Docs>
-        <summary>To be added.</summary>
+        <summary>Gets or Sets whether the dialog will be automatically upgraded to enable new features.</summary>


Suggested change

<summary>Gets or Sets whether the dialog will be automatically upgraded to enable new features.</summary>

<summary>Gets or sets whether the dialog will be automatically upgraded to enable new features.</summary>

The xml-doc is updated

RussKie · 2019-08-14T10:38:30Z

xml/System.Windows.Forms/GridItem.xml

-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+We don't do set because of the value class semantics, etc.


Please remove

RussKie · 2019-08-14T11:15:01Z

xml/System.Windows.Forms/PropertyManager.xml

-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+no op on the propertyManager


Suggested change

no op on the propertyManager

No-op, always returns `0`.

The xml-doc is updated

RussKie · 2019-08-14T11:18:55Z

xml/System.Windows.Forms/TextBox.xml

@@ -970,7 +970,7 @@
        <ReturnType>System.String</ReturnType>
      </ReturnValue>
      <Docs>
-        <summary>To be added.</summary>
+        <summary>Gets or sets the text that is displayed when the control has no Text and is not on focus.</summary>


Suggested change

<summary>Gets or sets the text that is displayed when the control has no Text and is not on focus.</summary>

<summary>Gets or sets the text that is displayed when the control has no <see cref="Text"/> and is not <see cref="Control.Focused"/>.</summary>

The xml-doc is updated

RussKie · 2019-08-14T11:22:54Z

xml/System.Windows.Forms/TextFormatFlags.xml

@@ -163,6 +163,11 @@
      <MemberValue>0</MemberValue>
      <Docs>
        <summary>Adds padding to the bounding rectangle to accommodate overhanging glyphs.</summary>
+        <remarks>


Please remove all of these.
The xml-doc is updated

mairaw · 2019-08-16T10:19:16Z

As I mentioned earlier, I've opened separate PRs for the relevant changes so I think this PR can be closed.

The only comment still left I believe is this one:
#2974 (comment)

RussKie · 2019-08-16T12:33:49Z

Thank you

Update WinForms docs

cd75803

RussKie changed the title ~~Update WinForms docs~~ WIP: Update WinForms docs Aug 9, 2019

mairaw reviewed Aug 9, 2019

View reviewed changes

xml/System.Windows.Forms.Design.Behavior/BehaviorServiceAdornerCollection.xml Outdated Show resolved Hide resolved

remove duplicate exceptions

7da3737

mairaw reviewed Aug 14, 2019

View reviewed changes

RussKie commented Aug 14, 2019

View reviewed changes

RussKie closed this Aug 16, 2019

RussKie deleted the update-winforms-docs branch August 16, 2019 12:33

mairaw mentioned this pull request Aug 19, 2019

Update docs for PropertyManager #3035

Merged

	<summary>Constructor that requires the object in question, the type of change and the remaining actionlists left for the object. on the related object.</summary>
	<summary>Constructor that requires the object in question, the type of change and the remaining actionlists left for the object on the related object.</summary>

	<summary>This EventArgs class is used by the DesignerActionService to signify that there has been a change in DesignerActionLists (added or removed) on the related object.</summary>
	<summary>This class is used by the <see cref="DesignerActionService"/> to signify that there has been a change in the <see cref="DesignerActionListCollection">designer action lists collection</see> (added or removed) on the related object.</summary>

	<summary>The type of changed that caused the related event to be thrown.</summary>
	<summary>The type of change that caused the related event to be thrown.</summary>

	<summary>An enum that defines what time of action happend to the related object's DesignerActionLists collection.</summary>
	<summary>An enum that defines what type of action happend to the related object's <see cref="DesignerActionListCollection">designer action lists collection</see>.</summary>

	<summary>This event is thrown whenever a request is made to show/hide the ui</summary>
	<summary>This event is thrown whenever a request is made to show/hide the UI.</summary>

	<summary>Gets or Sets whether the dialog will be automatically upgraded to enable new features.</summary>
	<summary>Gets or sets whether the dialog will be automatically upgraded to enable new features.</summary>

	<summary>Gets or sets the text that is displayed when the control has no Text and is not on focus.</summary>
	<summary>Gets or sets the text that is displayed when the control has no <see cref="Text"/> and is not <see cref="Control.Focused"/>.</summary>

WIP: Update WinForms docs #2974

WIP: Update WinForms docs #2974

Uh oh!

Conversation

RussKie commented Aug 9, 2019

Summary

Uh oh!

Uh oh!

mairaw commented Aug 12, 2019

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mairaw commented Aug 16, 2019

Uh oh!

RussKie commented Aug 16, 2019

Uh oh!

Uh oh!