Style guide for links/references/citations in docs

[huonw]

e.g. I used one style in rand http://static.rust-lang.org/doc/master/rand/struct.XorShiftRng.html

[1]: Marsaglia, George (July 2003). "Xorshift RNGs". Journal of Statistical Software. Vol. 8 (Issue 14).

And others have used other styles elsewhere.

(Part of #4361.)

[lucab]

Speaking of references, the [1] looks a bit weird when appearing in the index page (and I suppose in other short doc references too). Maybe it's better to put references in the body only?

Moreover, what about linking to doi entries (where possible) as to avoid maintenance burden for dead/moved links?

[huonw]

Both of those sound reasonable to me. (It's a while ago now, but IIRC, I couldn't track down doi entries for several of the references in rand, but, I did for, e.g. Gamma.)

[lucab]

Do we have a canonical document for such advises? I see some hints in rustdoc manual and some other in wiki notes.

In preparation for Sunday doc sprint, it would be good to try to uniform. I'll try to come up later with a draft wiki page, to be later discussed and finally sent as PR to rustdoc manual. Sounds ok?

[huonw]

There's the style guide and the issue #4361 too.

[huonw]

Another point here: some types/traits will have multiple doc-blocks with citations (e.g. a citation on the main doc description, and then some specialised method gets its own one); do we want to try to have these global across a page? (even if it's just numbered globally, although we could try to place them all together too)