Should we have a way of compiling/testing the code in the standard?

[jskeet]

It would be nice if we could validate that code in the standard compiles (where it's meant to) and has the output we claim it has.

This comes with all kinds of challenges, such as where "extra" code (which is described briefly but not provided in the spec) should live, how we test it etc.

This issue is basically for discussion of what we want to do, and how we might achieve it.

[svick]

One option is to copy what .Net docs do: have a regular project (with .csproj and .cs files) for a group of snippets, where the code looks e.g. like this:

namespace HelloWorld;

public class HelloWorld
{
    public static void Main(string[] args)
    {
        // <MainMethod>
        Console.WriteLine("What is your name?");
        var name = Console.ReadLine();
        var currentDate = DateTime.Now;
        Console.WriteLine($"{Environment.NewLine}Hello, {name}, on {currentDate:d} at {currentDate:t}!");
        Console.Write($"{Environment.NewLine}Press any key to exit...");
        Console.ReadKey(true);
        // </MainMethod>
    }
}

The relevant part of the code is then included in the text using non-standard Markdown, like this:

:::code language="csharp" source="./snippets/with-visual-studio-6-0/csharp/Program.cs" id="MainMethod":::

This has the advantage that it should make things easy when displaying the spec on the .Net docs site and that there are some existing tools that help with this (mainly VS Code integration). I don't know what effect this would have on the rest of the tooling.

[jskeet]

@svick: Possibly. Although personally, for ease of editing and reading the raw Markdown spec, I think I'd like it to be the other way round in this case - that the raw code is in the spec, and then it's extracted when we want to run it.

[markjulmar]

@jskeet The approach laid out by @svick is related to how docs.microsoft.com processes and publishes Markdown content - so it relies on a Markdig extension built by the docs team. It would only work cleanly if this repo were published to docs and not intended to be read directly from GitHub. I don't believe that is the case - is that correct?

[jskeet]

@markjulmar: That's correct. @BillWagner is probably the best person to take the lead on options here, being both on the ECMA technical group and deeply involved in the MS docs.

[BillWagner]

@markjulmar

That's correct: This repo is a dependent repo for dotnet/docs, which is onboarded in OPS.

This repo also has different publishing requirements: The ECMA committee needs to submit the standard in Word or PDF format. We have a tool we maintain for that purpose.

I'm currently investigating two different options:

• Using the Markdig extension built by the docs team. I'd asked Mark's team internally for an opinion on if it would just work.
• Using .NET Try / C# Interactive. I've reached out to that team, and I'll report back here what I find on that case.

[jskeet]

I'm spiking this now - and it's already found a bug in the spec (an example where we're missing a class body).

[RexJaeschke]

Heads up! I am working with Jon to add the appropriate HTML-example-extraction comments to the md files. My plan is to work on the files in chapter number order with Jon reviewing my PRs.

In my research thus far, I have identified some cases that are not handled by the tooling:

• Examples that are intended to throw an exception.
• Examples that are not completely self-contained, and need supporting preamble code (such as declarations) to compile.

Note that examples that are self-contained, but are not inside a class will compile with the latest VS compiler, which supports top-level statements.

This work will be tracked by Issue #646.

Jon will look at adding support for these new cases.

[jskeet]

Closing as we now have lots of examples, and more coming. #646 keeps track of tricky bits.