Improve code documentation

[celinval]

StableMIR definitions could use some comments.

I don't know what is the best way to move forward to avoid duplicating rustc's documentation plus adding more comments.

[momvart]

I don't know what is the best way to move forward to avoid duplicating rustc's documentation

We can add "See also [xyz](item in rustc's mir)" but I'm not sure if any reference to the compiler should be avoided or not.

[celinval]

Would that work with crates.io documentation? I tried to find a way to "inline" a linked documentation, but no luck.

[momvart]

I tried to find a way to "inline" a linked documentation, but no luck.

No experience unfortunately.

Although I'm not sure what you exactly mean by inlining, is it necessary to inline them? By default, they appear as links to the official online rustc's documents.

[celinval]

I mean, this is definitely an improvement to what we have today, but it won't work once we publish the stable mir crate in crates.io.

[celinval]

The link will likely be broken