doc: improve documentation for go.library_to_source attr param (bazel-contrib#2665)

attr["deps"] may be a list of either Targets or GoArchive.

Fixes bazel-contrib#1784

Author: Jay Conrod

go/private/context.bzl

@@ -187,17 +187,18 @@ def _merge_embed(source, embed):
     source["cgo_exports"] = source["cgo_exports"] + s.cgo_exports
 
 def _dedup_deps(deps):
-    """Returns a list of targets without duplicate import paths.
+    """Returns a list of deps without duplicate import paths.
 
     Earlier targets take precedence over later targets. This is intended to
     allow an embedding library to override the dependencies of its
     embedded libraries.
+
+    Args:
+      deps: an iterable containing either Targets or GoArchives.
     """
     deduped_deps = []
     importpaths = {}
     for dep in deps:
-        # TODO(#1784): we allow deps to be a list of GoArchive since go_test and
-        # nogo work this way. We should force deps to be a list of Targets.
         if hasattr(dep, "data") and hasattr(dep.data, "importpath"):
             importpath = dep.data.importpath
         else:

go/toolchains.rst

@@ -879,8 +879,18 @@ build mode.
 +--------------------------------+-----------------------------+-----------------------------------+
 | :param:`attr`                  | :type:`ctx.attr`            | |mandatory|                       |
 +--------------------------------+-----------------------------+-----------------------------------+
-| The attributes of the rule being processed. In a normal rule implementation this would be        |
-| ctx.attr.                                                                                        |
+| The attributes of the target being analyzed. For most rules, this should be                      |
+| ``ctx.attr``. Rules can also pass in a ``struct`` with the same fields.                          |
+|                                                                                                  |
+| ``library_to_source`` looks for fields corresponding to the attributes of                        |
+| ``go_library`` and ``go_binary``. This includes ``srcs``, ``deps``, ``embed``,                   |
+| and so on. All fields are optional (and may not be defined in the struct                         |
+| argument at all), but if they are present, they must have the same types and                     |
+| allowed values as in ``go_library`` and ``go_binary``. For example, ``srcs``                     |
+| must be a list of ``Targets``; ``gc_goopts`` must be a list of strings.                          |
+|                                                                                                  |
+| As an exception, ``deps``, if present, must be a list containing either                          |
+| ``Targets`` or ``GoArchives``.                                                                   |
 +--------------------------------+-----------------------------+-----------------------------------+
 | :param:`library`               | :type:`GoLibrary`           | |mandatory|                       |
 +--------------------------------+-----------------------------+-----------------------------------+