EventLogReader.ReadEvent - documenting null return

[daiplusplus]

Summary

The documentation for EventLogReader.ReadEvent does not indicate how to detect being at the last result (it returns null, but this isn't documented at all) - so this PR adds that detail.

Fixes #8206

[dotnet-issue-labeler]

I couldn't figure out the best area label to add to this PR. If you have write-permissions please help me learn by adding exactly one area label.

[opbld33]

Docs Build status updates of commit 6b3bb53:

✅ Validation status: passed

File	Status	Preview URL	Details
xml/System.Diagnostics.Eventing.Reader/EventLogReader.xml	✅Succeeded	View

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:

• Try searching the docs.microsoft.com contributor guides
• Post your question in the Docs support channel

[opbld31]

Docs Build status updates of commit 1f55fa5:

✅ Validation status: passed

File	Status	Preview URL	Details
xml/System.Diagnostics.Eventing.Reader/EventLogReader.xml	💡Suggestion	View	Details

xml/System.Diagnostics.Eventing.Reader/EventLogReader.xml

• Line 0, Column 0: [Suggestion: disallowed-html-tag - See documentation] HTML tag 'format' isn't allowed. Replace it with approved Markdown or escape the brackets if the content is a placeholder.
• Line 0, Column 0: [Suggestion: disallowed-html-tag - See documentation] HTML tag 'format' isn't allowed. Replace it with approved Markdown or escape the brackets if the content is a placeholder.

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:

• Try searching the docs.microsoft.com contributor guides
• Post your question in the Docs support channel

[ghost]

Tagging subscribers to this area: @tommcdon
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Summary

The documentation for EventLogReader.ReadEvent does not indicate how to detect being at the last result (it returns null, but this isn't documented at all) - so this PR adds that detail.

Fixes #8206

Author:	Jehoel
Assignees:	-
Labels:	area-System.Diagnostics
Milestone:	-

[gewarren]

Suggested change

	<summary>Reads and returns the next event from the event query results - or null if the end of the results has been reached.</summary>
	<summary>Reads and returns the next event from the event query results, or null if the end of the results has been reached.</summary>

[gewarren]

Suggested change

	<summary>Reads and returns the next event from the event query results - or null if the end of the results has been reached.</summary>
	<summary>Reads and returns the next event from the event query results.</summary>

[daiplusplus]

Methinks I should add the <returns> element back…

…but why remove the important details about null here?

[gewarren]

Suggested change

	<returns>Returns an <see cref="T:System.Diagnostics.Eventing.Reader.EventRecord" /> object - or a null reference.</returns>
	<returns>Returns an <see cref="T:System.Diagnostics.Eventing.Reader.EventRecord" /> object, or a null reference if the end of the results has been reached.</returns>

[gewarren]

Suggested change

	Each time this method is called the reader will advance to the next event record in its query results or the log file being read.
	Each time this method is called, the reader advances to the next event record in the query results or the log file.

[gewarren]

Suggested change

	When the reader reaches the end of the query results or log file the method will return null on its next call, but subsequent calls will throw an InvalidOperationException.
	When the reader reaches the end of the query results or log file, the method returns <c>null</c> on its next call, and subsequent calls will throw an <see cref="T:System.InvalidOperationException" />.

[gewarren]

Suggested change

	The returned EventRecord objects implement IDisposable and should be disposed of appropriately. To avoid leaking resources consider copying desired data from the EventRecord object into a custom class or tuple and then immediately disposing of the returned EventRecord before advancing to the next logged event.
	The returned EventRecord objects implement IDisposable and should be disposed of appropriately. To avoid leaking resources, consider copying desired data from the EventRecord object into a custom class or tuple and then immediately disposing of the returned EventRecord before advancing to the next logged event. The following code shows an example.

[gewarren]

The example should be code-fenced.

[daiplusplus]

Pardon my ignorance, but what is code-fencing? Also, what about the build validation warnings about <format> being invalid HTML? (…and I’m not even writing HTML, weird)

[gewarren]

Suggested change

	<exception cref="T:System.InvalidOperationException">Thrown when ReadEvent is called again after a previous call returned null.</exception>
	<exception cref="T:System.InvalidOperationException">ReadEvent was called again after a previous call returned null.</exception>

[daiplusplus]

I’m unsure if I should retain the <exception> reference to EventLogReaderException even though it’s redundant as the other exception types are subclasses thereof) - is it possible to render a hierarchical exception type list here?

[gewarren]

Please make all the same changes below.