Update delegates-overview.md

[mpostol]

@BillWagner My point is, that this article is hard to understand and inconsistent with the documentation as one whole.. Let's continue working on delegates and events concepts. I have just provided a preface to a document, which should describe both concepts but only describes delegate as C# implementation. Consider creating an independent introductory and independent document common for delegate and event concepts.

Summary

1. This conceptual article is only about delegates but should provide an introduction to delegates and events.
2. The conceptual article should not refer to a concrete implementation (C#).
3. Consider adding a common article providing a general introductory delegate and event preface.

---

Internal previews

📄 File	🔗 Preview link
docs/csharp/delegates-overview.md	docs/csharp/delegates-overview

[mpostol]

@BillWagner are there any plans related to this pr?

FYI: I want to contribute to this and similar issues through a video publication Programming in Practice - Delegates and Events

Events and delegates control flow, exchange data, and notify a condition change backed by code samples.

Referring to our previous conversation => @SamHobbsOrg - Mariusz Postol

[BillWagner]

@mpostol

For the time being, I'd like to keep any edits small. For historical reasons, there are two very similar sections in the C# guide that explain delegates this one, and a similar section in the programming guide.

I plan on combining these two sections after the November release of .NET 9. Before then, I only want to consider changes that are small in scope.

Yes, these additional paragraphs are small in scope. I don't think this adds any clarity. It defines other uses of the same words. I don't think that's helpful.

But, I do agree that this article currently assumes too much knowledge.

Instead, how about a single small paragraph that defines the concepts of "delegate" and "event" in the concept of C#. Something like:

A delegate is an object that represents a function. It enables callers to provide code to an API. An event provides a mechanism for an object to notify subscribers. Events are built on delegates.

[mpostol]

@BillWagner

@mpostol

For the time being, I'd like to keep any edits small. For historical reasons, there are two very similar sections in the C# guide that explain delegates this one, and a similar section in the programming guide.

I plan on combining these two sections after the November release of .NET 9. Before then, I only want to consider changes that are small in scope.

Yes, these additional paragraphs are small in scope. I don't think this adds any clarity. It defines other uses of the same words. I don't think that's helpful.

But, I do agree that this article currently assumes too much knowledge.

Instead, how about a single small paragraph that defines the concepts of "delegate" and "event" in the concept of C#. Something like:

A delegate is an object that represents a function. It enables callers to provide code to an API. An event provides a mechanism for an object to notify subscribers. Events are built on delegates.

My knowledge about delegates and events comes only from my experience and general knowledge. Thanks to this opportunity I have just reviewed the documentation and defined the following entry points related to the topic:

.NET fundamentals documentation:

• Handle and raise events - this conceptual documentation should be harmonized with the presentation.
• Generic Delegates for Manipulating Arrays and Lists
• Delegates and lambdas
• How to: Hook up a delegate using reflection

C# documentation:

• Delegates (C# Programming Guide)
• C# Concept-Delegates & Events - Introduction to delegates and events in C#

C# language reference:

• event (C# reference)
• Built-in reference types (C# reference)-The delegate type
• Addition operators - + and +=
• - and -= operators - subtraction (minus)
• delegate operator

It is only my first attempt. I must say that the documentation is overloaded in this respect. Many places describe similar things using different terms hard to understand. For example, hooking delegate, and converting a lambda to delegate to notify only a few ones. I understand that hooking means an assignment in the context of reflection. Again, it is impossible to convert a lambda to a delegate. I understand that they are kind of shortcuts, but my point is that simplification is not the mother of simplicity. Concluding if you need any help in this respect I am a willing helper.

BTW, where mapping file, defining the content of the documentation suits, can be found? Now I see my proposal in the context of a particular file but not in the context of the architecture of a documentation suit. It seems to me that the title of this section partiality is cloned in an additional document in the same section. If I remember correctly, it could confuse reader which one documentation entry should be checked out to learn introduction to events.

Yes, these additional paragraphs are small in scope. I don't think this adds any clarity. It defines other uses of the same words. I don't think that's helpful.

My proposal describes the concept and should be placed in the conceptual documentation detached from the particular programming language. My point is that, by design, the conceptual documentation suit should not refer to the concrete programming language because the same concepts (e.g. delegates and events) have been with us for ages even before C# adge. This way we can offer the documentation even to people not serious about C#. Again, if you need any help I am open to proposals.

Instead, how about a single small paragraph that defines the concepts of "delegate" and "event" in the concept of C#. Something like:

I agree there should be a conceptual introduction to delegates and events in the context of type-safe pointers to methods (references). Methods but not functions, because, according to my knowledge, a function is a method returning a value. If there is no return value we have procedures. Methods cover both. In your proposal API (application program interface) refers probably to the .NET library but the usage of delegates is much broader, for example in concurrent programming, asynchronous programming, WPF, etc. Simplification in this respect could be confusing.

Finally, my proposal is as follows:

1. Change the title of the article if you like it or reject the pr
2. Finish your work planned for a new software release
3. Contact me to discuss and plan further work on delegates/events/anonymous functions if you think I could help you including but not limited to merging the pointed-out articles.