Clarify LINQ syntax explanation in documentation

[jp2images]

Clarification

Updated the explanation of LINQ syntax to clarify the use of method syntax with lambda expressions.

I am reading the docs for the first time, learning how to use this excellent API on a project.

[idg10]

The thing that troubles me slightly about this edit is that it implies that the lambda expression is as significant as the method invocation. That would be the case when talking about a LINQ provider that uses Expression<Func<...>> (e.g., Entity Framework, or even IObservable<T>'s expression-tree-based relative, IQbservable,<T>) because you really do need a lambda expression if you move over to method invocation syntax with those kinds of providers.

But with LINQ providers that just use Func<...> (e.g., Rx, and also LINQ to Objects) you can invoke their operators directly using method syntax without necessarily having to use a lambda expression. E.g., you could write:

bool TradeIsLarge(Trade trade)
{
    return trade.Volume > 1_000_000;
}

var bigTrades = trades.Where(TradeIsLarge);

And in a way, this is actually a more direct representation of what's going on. With simple delegate-based LINQ providers, the compiler will turn any lambda into a method, and will pass a delegate to that method, so the compiler effectively transforms the lambda-based code into something like the above. (That's not true for expression-tree-based LINQ providers of course.)

Invocation of LINQ operator methods is fundamental to Rx, but as this example shows, use of lambda expressions is not.

So for that reason, I don't want to accept this edit as-is. I don't want to give lambdas equal prominence with method invocation here, because method invocation is the only fundamentally necessary thing here.

So what I'd like to ask is: what problem are you trying to fix here? Normally when someone suggests an edit, I can understand what they found unclear, so in cases like this where I think the proposed change creates a new problem, I can normally come up with suggestions that address that problem without also creating what I see as new problems.

But in this case, I'm not confident I've understood what you found problematic with the current text. Is it that it wasn't clear that "invoking LINQ operators" just means using method calls? If that's the issue, then I don't think we really need to call out the fact that we're using a lambda. We could just write:

If you don't like the query expression syntax, you can write exactly equivalent code by using method syntax:

or maybe:

If you don't like the query expression syntax, invoking LINQ operators using method syntax is exactly equivalent:

Whatever we do, I want to keep the focus here on the methods: the key point is that you build an Rx query through a series of method invocations.