Finish docs on existing rustdoc

[steveklabnik]

I'm filing this issue here rather than on rust-lang/rust because it's more relevant to people on this repo, but https://github.com/rust-lang/rust/tree/master/src/doc/rustdoc is the docs for the old rustdoc, and we should fill it out so that we can determine if we're compatible with the older rustdoc, and how much.

Filling these out is important:

• What is rustdoc?
• Command-line arguments
• In-source directives
• Documentation tests
• Plugins
• Passes

Marking this as "easy" because it mostly requires reading code, not writing it. I'm happy to elaborate a bit more about the details here if needed!

[chordowl]

cc rust-lang/rust#42322

[gnzlbg]

This documentation misses actually the syntax allowed in documentation comments.

Ok, it does mention markdown, but the current rustdoc supports crosslinking methods, functions, traits, etc. It would be nice to document all of this because many projects are using these.

[steveklabnik]

but the current rustdoc supports crosslinking methods, functions, traits,

Since when?

[gnzlbg]

Since as far as I can remember: https://rust-lang-nursery.github.io/stdsimd/x86_64/stdsimd/vendor/constant._MM_EXCEPT_DENORM.html

There is a See _mm_setcsr in that page, that is a cross link. You can have a function link against trait methods, struct data members, enum variants, etc. It seems to rely on the adhoc way in which rustdoc generates lables and the html pages for the items, but... it works, and many projects use this.

[steveklabnik]

Right, but that's just markdown. Look at the source:

/// See [`_mm_setcsr`](fn._mm_setcsr.html)

That's a manual link. Just markdown.

[gnzlbg]

Ah yes, sure. I was just saying that being able to create these links depends on how rustdoc currently creates the files (e.g. that it puts functions into fn.{{function_name}}.html files) so we might as well document that.

[steveklabnik]

This is effectively complete for our purposes here. Obviously the rustdoc book can be improved, but that's not a thing to track in this repo.