Documentation Conventions

[Johannes Rudolph]

Hi Team,

Inspired by Jon's recent blog post on LINQ operator behavior, I've compiled a set of conventions about how we should document our operators. It is roughly based on John's suggestion but also takes into account how most of the operators were already documented. A clean documentation is especially necessary to evaluate performance implications of an operator chain.

I aligned all operators in the trunk with this convention and made sure ever operator has it's behavior documented. I've also put up a wiki page on our project site that lists these conventions.

I know there hasn't been much progress in the last months, but I'd really like to get your feedback on this (agree/disagree?).

Kind regards,

Johannes Rudolph

[Jon Skeet]

You appear to be contrasting "immediate execution" with "deferred execution" - but your definition would include "OrderBy" in both camps. I'd use the aggregate operators (Count etc) as examples of immediate execution.

To be honest, I suspect the clearest way forward is to explain exactly what will happen for each operator and not even try to use a shorthand. Maybe I'm just being too cynical before my first coffee of the day.

Jon

--
You received this message because you are subscribed to the Google Groups "MoreLINQ Developers" group.
To post to this group, send email to moreli...@googlegroups.com.
To unsubscribe from this group, send email to morelinq-dev...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/morelinq-dev?hl=en.

--
You received this message because you are subscribed to the Google Groups "MoreLINQ Developers" group.
To post to this group, send email to moreli...@googlegroups.com.
To unsubscribe from this group, send email to morelinq-dev...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/morelinq-dev?hl=en.

[Johannes Rudolph]

Hi Jon,

we're on the same page here.  What I meant with immediate execution was 'returns a scalar value immediately'. This applies to count() as it does to consume. The idea behind having a convention was to explain what these keywords mean, so they can be used with consistence to document our operators behavior. Every operator needs to document its (special) behavior in detail (e. g. ExceptBy):

/// <remarks>

/// This is a set operation; if multiple elements in <paramref name="first"/> have

/// equal keys, only the first such element is returned.

/// This operator uses deferred execution and streams the results, although

/// a set of keys from <paramref name="second"/> is immediately selected and retained.

/// </remarks> The keywords are definately useful to describe the operators, but they do not replace a detailed and accurate description. Sorry for the bad formatting, I'm sitting in school atm and hacked this mail on my iPhone. Johannes

 am

[Johannes Rudolph]

Hi Jon,

what do you think? I have refined the wording in the wiki to make sure it's not a categorization rather than a description of keywords used when describing an operators behavior:

This list serves as a description of certain keywords we use to describe an operators behavior, it does not describe a set of categories an operator can be put in. Although some keywords appear to describe opposite behavior, they are sometime used on the same operator to exactly describe the evaluation of its inputs.

 

Re your argument about OrderBy:

A hypothetic OrderBy() has to sort the entire sequence before it returns the first element. But it does defer enumerating and sorting its inputs until the latest possible moment, which is until the first result element is requested. OrderBy does therefore use deferred execution. Since it must sort all elements at the point the result is requested, it enumerates the source sequence, sorts it and then buffers the result. Streaming the source sequence would be impossible because it could not be sorted correctly. Implementers of OrderBy could now decide wether they want to return the buffer or stream the buffered results.

Hope this clears things up a little. I think it is unavoidable we need to come up with a clear description of the keywords we have used so far.

Kind regards,

Johannes