docs: Overhaul the documentation for SIL and add a new SIL printing mode

[eeckstein]

The main changes in the documentation are:

• Created a new directory docs/SIL and moved all SIL-related files into this directory.

• Converted rst files to markdown.

• Extracted sections from SIL.md which go into very much detail - including the instruction reference - into separate files: Types.md, Ownership.md, FunctionAttributes.md, Instructions.md. Those files are referenced from SIL.md at the relevant places.

• Rewrote and updated the OSSA part in SIL.md

• Removed a few sections, which are not relevant anymore, like "Value dependency" (which is replaced by ownership concepts).

• Fixed and improved a lot of small things.

[gottesmm]

Just some small flow comments.

[gottesmm]

e.g. -> e.x.

e.g. means that is... I think you mean for example which is e.x.

[nate-chandler]

e.g. -- for example ( https://en.wiktionary.org/wiki/e.g. )
i.e. -- that is ( https://en.wiktionary.org/wiki/i.e. )

[atrick]

I'm alarmed to see e.x. anywhere in our docs. what is that?

[gottesmm]

"the forward-extended lifetime of the value". Or something like that.

On another note, I like the diagram below.

[eeckstein]

A forward-extended lifetime does not refer to a single value. It involves multiple values, even multiple definitions (producers).
I think this is important to know and I added a paragraph+example for this.

[gottesmm]

I think this is another case where you mean e.x. instead of e.g.

[gottesmm]

Maybe ignore the merging comment I made, since we talk about it here.

[atrick]

💯 on

• -emit-pure-sil
• documentation structure
• OSSA examples (they look familiar, good to have them in the docs)

I don't think we need to worry about typos here or there in this PR

[rjmccall]

I love the SIL documentation restructuring, that seems great.

Having a SIL printing mode that suppresses all the theoretically-helpful comments feels like a totally reasonable feature, albeit one that should be added in a separate PR from the docs rework. I don't like the idea of having multiple dialects of SIL itself, though — if we agree that this is a better way to write SIL, we should just change SIL. (We can probably write a script to mass-update the tests.)

The idea of removing types from printed operands is interesting. A lot of instructions already avoid operand types when they're redundant with other information in the instruction, and that's something we could pretty easily just do more of without dramatically changing how we parse SIL. If we want to do it in general by propagating type information from the value definition, we're going to run into the problem that basic blocks are not required to appear in an order consistent with dominance — SILGen usually (always?) emits them this way, but CFG optimizations can definitely mess that up. The general solution to that problem is to introduce a parse tree, although I suppose we could also just recognize that we're processing out of order and skip tokens until we reach the next block. Or we could make operand types optional and then only print them when blocks are rendered out of order? Or maybe when we've already rendered that instruction — the difference being that we'd sometimes still print operand types when rendering a subset of the function, e.g. when dumping a single instruction or basic block.

[eeckstein]

one that should be added in a separate PR from the docs rework.

Yes, that makes sense. I removed the SIL printing commit and will put it into a separate PR.

[eeckstein]

@swift-ci smoke test