Improved internal and external documentation

[UebelAndre]

Changes:

• Added documentation containing type information for a large number of macros
• Cleans up doc attributes so stardoc renders cleaner
• Adds new pages to the docs/update_docs.sh output
• Rearranged a few macros to reduce code duplication
• Fixed some incompatibility warnings/buildifier defects

@acmcarther @mfarrugi @damienmg @smklein @dfreese
I would hugely appreciate if all code owners would take a look at 548d62f and provide suggestions on how the documentations can be improved. I'm very bad at writing docs and this was largely a learning exercise for me so some of the docs may not be as clear as they should be. There are a few I was totally unsure of what to write (namely get_compilation_mode_opts, _determine_lib_name, rust_toolchain, and RustProtoInfo).

Again, It'd help out tremendously to have these docs updated. Looking forward to suggestions 😄

edit: The commit of the big request for suggestions has been moved to #420

[damienmg]

Comment by change:

• Renamed RustProtoProvider -> RustProtoInfo: I don't see the use of this change, Provider is a more common name and I find it more explicit
• Partially addressed legacy provider syntax issue: LGTM
• Renamed AliasableDep -> AliasableDepInfo: Can we rename as AliasedDepProvider instead?
• Renamed relative_path -> relativize: Some nit inlined
• Moved get_lib_name to //rust:private/utils.bzl: This change is adding an unused function, drop?
• Updated copyright: Please do not do this, we should not update existing Copyright lines.
• _Moved determine_output_hash so it can be used in other places: LGTM
• Updating documentation: this change is too big, please extract to a separate PR.
• Added more pages to the outward facing docs: Some nit inlined
• Regenerate documentation: LGTM

[UebelAndre]

* **Renamed RustProtoProvider -> RustProtoInfo**: I don't see the use of this change, Provider is a more common name and I find it more explicit

Buildifier claims this violates naming conventions: https://github.com/bazelbuild/buildtools/blob/master/WARNINGS.md#name-conventions

[UebelAndre]

* **AliasableDepInfo**: Can we rename as `AliasedDepProvider` instead?

Again, this violates https://github.com/bazelbuild/buildtools/blob/master/WARNINGS.md#name-conventions

[UebelAndre]

* **Moved get_lib_name to //rust:private/utils.bzl**: This change is adding an unused function, drop?

If it was unused, I would have removed it. It's used in rustc.bzl and rustdoc_test.bzl

[damienmg]

* **Renamed RustProtoProvider -> RustProtoInfo**: I don't see the use of this change, Provider is a more common name and I find it more explicit

Buildifier claims this violates naming conventions: https://github.com/bazelbuild/buildtools/blob/master/WARNINGS.md#name-conventions

Meh :/ This is a bad convention, anyway that's the convention so this change LGTM.

* **Moved get_lib_name to //rust:private/utils.bzl**: This change is adding an unused function, drop?

If it was unused, I would have removed it. It's used in rustc.bzl and rustdoc_test.bzl

This change only add the function without any call site. Unless the code was broken before this method is not used anywhere. You probably forgot to update the load statements and remove the original place of the code.

[UebelAndre]

This change only add the function without any call site. Unless the code was broken before this method is not used anywhere. You probably forgot to update the load statements and remove the original place of the code.

Ah I see, I've updated this now. I didn't completely break out this change from the larger one. This has been updated

[UebelAndre]

* Please do not do this, we should not update existing Copyright lines.

Dropped but can you update it then?

[UebelAndre]

* **Updating documentation**: this change is too big, please extract to a separate PR.

Moving to another PR.

edit: See #420

[damienmg]

* Please do not do this, we should not update existing Copyright lines.

Dropped but can you update it then?

We should not touch to the copyright line. The date should be the date of creation of the file as per guidance from the opensource office at google.

[damienmg]

Just one nit left.