8000 Fix some threading docs by kouvel · Pull Request #4961 · dotnet/dotnet-api-docs · GitHub
[go: up one dir, main page]

Skip to content

Fix some threading docs #4961

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.

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
merged 7 commits into from
Oct 27, 2020
Merged

Fix some threading docs #4961

merged 7 commits into from
Oct 27, 2020

Conversation

kouvel
Copy link
Contributor
@kouvel kouvel commented Oct 8, 2020

Fixes dotnet/runtime#35519
Fixes dotnet/runtime#35518
Fixes #4585
Fixes #4448

@kouvel kouvel requested a review from mangod9 October 8, 2020 06:56
@kouvel kouvel self-assigned this Oct 8, 2020
@opbld34
Copy link
opbld34 commented Oct 8, 2020

Docs Build status updates of commit 03461d5:

⚠️ Validation status: warnings

File Status Preview URL Details
xml/System.Threading/EventWaitHandle.xml ⚠️Warning View Details
samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.interlocked.decrement/cs/decrement1.cs ✅Succeeded View
samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.interlocked.decrement/cs/decrement2.cs ✅Succeeded View
samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.interlocked.increment2/cs/increment3.cs ✅Succeeded View
samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.interlocked.increment2/cs/increment4.cs ✅Succeeded View
xml/System.Threading/EventWaitHandleAcl.xml ✅Succeeded View
xml/System.Threading/ExecutionContext.xml ✅Succeeded View
xml/System.Threading/Mutex.xml ✅Succeeded View
xml/System.Threading/MutexAcl.xml ✅Succeeded View
xml/System.Threading/Semaphore.xml ✅Succeeded View
xml/System.Threading/SemaphoreAcl.xml ✅Succeeded View

xml/System.Threading/EventWaitHandle.xml

  • Line 0, Column 0: [Warning-ECMA2Yaml_MemberNameAndSignature_NotUnique] Member .ctor's name and signature is not unique
  • Line 0, Column 0: [Warning-ECMA2Yaml_MemberNameAndSignature_NotUnique] Member .ctor's name and signature is not unique

For more details, please refer to the build report.

If you see build warnings/errors with permission issues, it might be due to single sign-on (SSO) enabled on Microsoft's GitHub organizations. Please follow instructions here to re-authorize your GitHub account to Docs Build.

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.

Note: Your PR may contain errors or warnings unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

For any questions, please:

@kouvel
Copy link
Contributor Author
kouvel commented Oct 19, 2020

Made a couple of fixes to note some subtle differences

@opbld30
Copy link
opbld30 commented Oct 19, 2020

Docs Build status updates of commit 440b9d2:

❌ Validation status: errors

Please follow instructions here which may help to resolve issue.

File Status Preview URL Details
❌Error Details

  • [Error-GitCommitDoesNotExist] Cannot sync git repo to specified commit because commit 440b9d2fcb867c78a29652106103d58a2ef47f1f doesn't exist. It might be caused your branch is deleted or force pushed. If it is not this case, please open a ticket on https://SiteHelp

For more details, please refer to the build report.

If you see build warnings/errors with permission issues, it might be due to single sign-on (SSO) enabled on Microsoft's GitHub organizations. Please follow instructions here to re-authorize your GitHub account to Docs Build.

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.

Note: Your PR may contain errors or warnings unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

For any questions, please:

@kouvel
Copy link
Contributor Author
kouvel commented Oct 19, 2020

Rebased to fix conflicts. The last two commits are new.

@kouvel kouvel closed this Oct 19, 2020
@kouvel kouvel reopened this Oct 19, 2020
@opbld33
Copy link
opbld33 commented Oct 19, 2020

Docs Build status updates of commit dade40b:

⚠️ Validation status: warnings

File Status Preview URL Details
xml/System.Threading/EventWaitHandle.xml ⚠️Warning View Details
samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.interlocked.decrement/cs/decrement1.cs ✅Succeeded View
samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.interlocked.decrement/cs/decrement2.cs ✅Succeeded View
samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.interlocked.increment2/cs/increment3.cs ✅Succeeded View
samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.interlocked.increment2/cs/increment4.cs ✅Succeeded View
xml/System.Threading/EventWaitHandleAcl.xml ✅Succeeded View
xml/System.Threading/ExecutionContext.xml ✅Succeeded View
xml/System.Threading/Mutex.xml ✅Succeeded View
xml/System.Threading/MutexAcl.xml ✅Succeeded View
xml/System.Threading/Semaphore.xml ✅Succeeded View
xml/System.Threading/SemaphoreAcl.xml ✅Succeeded View

xml/System.Threading/EventWaitHandle.xml

  • Line 0, Column 0: [Warning-ECMA2Yaml_MemberNameAndSignature_NotUnique] Member .ctor's name and signature is not unique
  • Line 0, Column 0: [Warning-ECMA2Yaml_MemberNameAndSignature_NotUnique] Member .ctor's name and signature is not unique

For more details, please refer to the build report.

If you see build warnings/errors with permission issues, it might be due to single sign-on (SSO) enabled on Microsoft's GitHub organizations. Please follow instructions here to re-authorize your GitHub account to Docs Build.

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.

Note: Your PR may contain errors or warnings unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

For any questions, please:

@opbld30
Copy link
opbld30 commented Oct 19, 2020

Docs Build status updates of commit dade40b:

⚠️ Validation status: warnings

File Status Preview URL Details
xml/System.Threading/EventWaitHandle.xml ⚠️Warning View Details
samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.interlocked.decrement/cs/decrement1.cs ✅Succeeded View
samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.interlocked.decrement/cs/decrement2.cs ✅Succeeded View
samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.interlocked.increment2/cs/increment3.cs ✅Succeeded View
samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.interlocked.increment2/cs/increment4.cs ✅Succeeded View
xml/System.Threading/EventWaitHandleAcl.xml ✅Succeeded View
xml/System.Threading/ExecutionContext.xml ✅Succeeded View
xml/System.Threading/Mutex.xml ✅Succeeded View
xml/System.Threading/MutexAcl.xml ✅Succeeded View
xml/System.Threading/Semaphore.xml ✅Succeeded View
xml/System.Threading/SemaphoreAcl.xml ✅Succeeded View

xml/System.Threading/EventWaitHandle.xml

  • Line 0, Column 0: [Warning-ECMA2Yaml_MemberNameAndSignature_NotUnique] Member .ctor's name and signature is not unique
  • Line 0, Column 0: [Warning-ECMA2Yaml_MemberNameAndSignature_NotUnique] Member .ctor's name and signature is not unique

For more details, please refer to the build report.

If you see build warnings/errors with permission issues, it might be due to single sign-on (SSO) enabled on Microsoft's GitHub organizations. Please follow instructions here to re-authorize your GitHub account to Docs Build.

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.

Note: Your PR may contain errors or warnings unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

For any questions, please:

@kouvel
Copy link
Contributor Author
kouvel commented Oct 19, 2020

Not sure what the validation warning is referring to, I don't see any non-unique constructor signatures

@kouvel
Copy link
Contributor Author
kouvel commented Oct 20, 2020

I think this is ready to merge. It looks like the approval has disappeared, maybe after I closed/reopened the issue to work around a CI validation issue above. @mangod9 could you please approve again?

@mangod9
Copy link
Member
mangod9 commented Oct 20, 2020

Approved again, but perhaps it requires approval from the docs team.

@kouvel
Copy link
Contributor Author
kouvel commented Oct 20, 2020

Thanks! @gewarren could you please also take a quick look?

Copy link
Contributor
@gewarren gewarren left a comment

Choose a reason for hiding this comment

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

I left a few suggestions, that if accepted, should be updated across all the files.
Also, it looks like the build warning about the duplicate .ctor is bogus - all 5 constructors look unique to me. I'll inquire with the team responsible for that.

@@ -53,20 +53,29 @@
<format type="text/markdown"><![CDATA[

## Remarks
The `name` may be prefixed with `Global\` or `Local\` to specify a namespace. When the `Global` namespace is specified, the synchronization object may be shared with any processes on the system. When the `Local` namespace is specified, which is also the default when no namespace is specified, the synchronization object may be shared with processes in the same session. On Windows, a session is a login session, and services typically run in a different non-interactive session. On Unixes, each shell has its own session. Session-local synchronization objects may be appropriate for synchronizing between processes with a parent/child relationship where they all run in the same session. For more information about synchornization object names on Windows, see https://docs.microsoft.com/windows/win32/sync/object-names.
Copy link
Contributor

Choose a reason for hiding this comment

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

Is "Unixes" a proper word? I'd suggest "On Unix operating systems...". Also, it looks like this paragraph is repeated throughout the PR, so please make the changes elsewhere too.

Suggested change
The `name` may be prefixed with `Global\` or `Local\` to specify a namespace. When the `Global` namespace is specified, the synchronization object may be shared with any processes on the system. When the `Local` namespace is specified, which is also the default when no namespace is specified, the synchronization object may be shared with processes in the same session. On Windows, a session is a login session, and services typically run in a different non-interactive session. On Unixes, each shell has its own session. Session-local synchronization objects may be appropriate for synchronizing between processes with a parent/child relationship where they all run in the same session. For more information about synchornization object names on Windows, see https://docs.microsoft.com/windows/win32/sync/object-names.
The `name` may be prefixed with `Global\` or `Local\` to specify a namespace. When the `Global` namespace is specified, the synchronization object may be shared with any processes on the system. When the `Local` namespace is specified, which is also the default when no namespace is specified, the synchronization object may be shared with processes in the same session. On Windows, a session is a login session, and services typically run in a different non-interactive session. On Unix operating systems, each shell has its own session. Session-local synchronization objects may be appropriate for synchronizing between processes with a parent/child relationship where they all run in the same session. For more information about synchronization object names on Windows, see [Object names](/windows/win32/sync/object-names).

Copy link
Contributor Author

Choose a reason for hiding this comment

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

It looks like "Unixes" is the common plural form and can also be used to refer to Unix-like systems. I think your suggestion is more clear, changed to "On Unix-like operating systems...".

<exception cref="T:System.Threading.WaitHandleCannotBeOpenedException">A system-wide synchronization event with the provided <paramref name="name" /> was not found.
-or- An <see cref="T:System.Threading.EventWaitHandle" /> with system-wide name <paramref name="name" /> cannot be created. An <see cref="T:System.Threading.EventWaitHandle" /> of a different type might have the same name.</exception>
.NET Framework only: <paramref name="name" /> is longer than MAX_PATH (260 characters).</exception>
<exception cref="T:System.ArgumentOutOfRangeException">The <paramref name="mode" /> enum value was out of legal range. In some cases <see cref="T:System.ArgumentException"/> is thrown, so use that instead.</exception>
Copy link
Contributor

Choose a reason for hiding this comment

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

What does "use that instead" mean? Do you mean "catch that instead"?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I didn't want to suggest catching this exception, I just removed that part and just noted the different exception that may be thrown. Also removed another similar usage for DirectoryNotFoundException.

@opbld34
Copy link
opbld34 commented Oct 20, 2020

Docs Build status updates of commit 9d8d720:

⚠️ Validation status: warnings

File Status Preview URL Details
xml/System.Threading/EventWaitHandle.xml ⚠️Warning View Details
samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.interlocked.decrement/cs/decrement1.cs ✅Succeeded View
samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.interlocked.decrement/cs/decrement2.cs ✅Succeeded View
samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.interlocked.increment2/cs/increment3.cs ✅Succeeded View
samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.interlocked.increment2/cs/increment4.cs ✅Succeeded View
xml/System.Threading/EventWaitHandleAcl.xml ✅Succeeded View
xml/System.Threading/ExecutionContext.xml ✅Succeeded View
xml/System.Threading/Mutex.xml ✅Succeeded View
xml/System.Threading/MutexAcl.xml ✅Succeeded View
xml/System.Threading/Semaphore.xml ✅Succeeded View
xml/System.Threading/SemaphoreAcl.xml ✅Succeeded View

xml/System.Threading/EventWaitHandle.xml

  • Line 0, Column 0: [Warning-ECMA2Yaml_MemberNameAndSignature_NotUnique] Member .ctor's name and signature is not unique
  • Line 0, Column 0: [Warning-ECMA2Yaml_MemberNameAndSignature_NotUnique] Member .ctor's name and signature is not unique

For more details, please refer to the build report.

If you see build warnings/errors with permission issues, it might be due to single sign-on (SSO) enabled on Microsoft's GitHub organizations. Please follow instructions here to re-authorize your GitHub account to Docs Build.

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.

Note: Your PR may contain errors or warnings unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

For any questions, please:

@kouvel
Copy link
Contributor Author
kouvel commented Oct 26, 2020

@gewarren could you please take a look at the changes above?

@kouvel kouvel merged commit 492ee8c into dotnet:master Oct 27, 2020
@kouvel kouvel deleted the DocsFixApi branch October 27, 2020 20:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
0