System.Linq.Enumerable TakeLast and SkipLast don't have XML docs

[tomzorz]

Hi dotnet-api-docs team.

As the title says System.Linq.Enumerable TakeLast and SkipLast don't have XML docs. Technically I'm opening a third issue on this after #1060 and #1061 but those two aren't really clear on the issue and as I dived in to do a PR I realized it's a tad more complex than just filling out the missing parts in this repo.

The complication dawned on me when I wanted to create the snippet samples first for the two extension methods here. Apparently the .csproj has <TargetFrameworks>netcoreapp2.2;net472</TargetFrameworks>, and neither methods are available under the net472 target:

After a little searching I've found this comment by @karelz dotnet/corefx#14186 (comment) which sheds some light on why weren't the docs added on release.

Some time has passed now, the shipping date is being announced in a month - my question is: is there a guideline for doing docs/samples for these kinds of APIs now?

If I wrap the samples in #if NETCOREAPP conditionals that solves the build issue, but I'd definitely add some sort of warning in there as well for those who'd just blindly copy the sample.

        #region SkipLast
        static void SkipLast()
        {
            // <Snippet203>
            #if NETCOREAPP
            int[] grades = { 59, 82, 70, 56, 92, 98, 85 };

            IEnumerable<int> topGrades =
                grades.OrderByDescending(g => g).SkipLast(3);

            Console.WriteLine("All grades except the bottom three are:");
            foreach (int grade in topGrades)
            {
                Console.WriteLine(grade);
            }
            #endif
            /*
             This code produces the following output:
            
             All grades except the bottom three are:
             98
             92
             85
             82
            */
            // </Snippet203>
        }
        #endregion

        #region TakeLast
        static void TakeLast()
        {
            // <Snippet204>
            #if NETCOREAPP
            int[] grades = { 59, 82, 70, 56, 92, 98, 85 };

            IEnumerable<int> bottomThreeGrades =
                grades.OrderByDescending(grade => grade).TakeLast(3);

            Console.WriteLine("The bottom three grades are:");
            foreach (int grade in bottomThreeGrades)
            {
                Console.WriteLine(grade);
            }
            #endif
            /*
             This code produces the following output:
            
             The bottom three grades are:
             70
             59
             56
            */
            // </Snippet204>
        }
        #endregion

[mairaw]

Hi @tomzorz! Thanks for your feedback. You don't have to use the same project to add the snippets. So you could create a new one that targets netcore only.

@karelz's team and our team are coming up with a plan to fill in the gaps and avoid this sort of problem in the future as well. I'm also currently working on publishing some writing guidelines for API docs. Part of that should be published soon.

I've added an up-for-grabs on the other two issues.

Other than that, the API docs should sort of follow the same pattern used for existing APIs. Content here, examples on dotnet/samples.
Is there anything else I could help you with to get started on contributing to the API docs?

[mairaw]

And then, once we have the docs here, the content should make into .NET Core IntelliSense.

[tomzorz]

@mairaw Awesome, thank you for clarifying.

Just one more question, if I were to create an Enumerable_netcore.csproj here would that be an acceptable solution? I'm assuming you might have a preference for the naming/location of the second netcore only project, so I thought I'd ask before I commit :)

[mairaw]

I was thinking more about this.

What if you add the conditional compilation but instead of leaving them inside the snippet you put them outside like this:

            #if NETCOREAPP
            // <Snippet203>
            int[] grades = { 59, 82, 70, 56, 92, 98, 85 };

            IEnumerable<int> topGrades =
                grades.OrderByDescending(g => g).SkipLast(3);

            Console.WriteLine("All grades except the bottom three are:");
            foreach (int grade in topGrades)
            {
                Console.WriteLine(grade);
            }
            /*
             This code produces the following output:
            
             All grades except the bottom three are:
             98
             92
             85
             82
            */
            // </Snippet203>
            #endif

Also, you don't need to use numbers if you don't want to. You can also give names like SnippetSkipLast and SnippetTakeLast, for example and then you refer them by name instead of number.

[tomzorz]

Sounds like a plan! I'll probably stick with the numbers though, just to stick with the pattern.

[tomzorz]

So the samples have been merged, when they're live I'll finish the actual docs.