chore: update docs

Author: alexeagle

docs/rules.md

@@ -18,7 +18,7 @@ _a_struct_type = type(struct())
 _a_string_type = type("")
 
 def _py_binary_or_test(name, rule, srcs, main, imports, deps = [], resolutions = {}, **kwargs):
-    # Compatibility with rules_python, see docs on find_main
+    # Compatibility with rules_python, see docs in py_executable.bzl
     main_target = "_{}.find_main".format(name)
     determine_main(
         name = main_target,
@@ -56,8 +56,10 @@ def py_binary(name, srcs = [], main = None, imports = ["."], resolutions = {}, *
     Args:
         name: name of the rule
         srcs: python source files
-        main: the entry point. If absent, then the first entry in srcs is used. If srcs is non-empty,
-            then this is treated as a suffix of a file that should appear among the srcs.
+        main: the entry point.
+            Like rules_python, this is treated as a suffix of a file that should appear among the srcs.
+            If absent, then "[name].py" is tried. As a final fallback, if the srcs has a single file,
+            that is used as the main.
         imports: List of import paths to add for this binary.
         resolutions: FIXME
         **kwargs: additional named parameters to the py_binary_rule
@@ -89,6 +91,8 @@ def py_binary(name, srcs = [], main = None, imports = ["."], resolutions = {}, *
 
 def py_test(name, main = None, srcs = [], imports = ["."], **kwargs):
     "Identical to py_binary, but produces a target that can be used with `bazel test`."
+
+    # Ensure that any other targets we write will be testonly like the py_test target
     kwargs["testonly"] = True
     _py_binary_or_test(name = name, rule = _py_test, srcs = srcs, main = main, imports = imports, **kwargs)
 

py/defs.bzl

@@ -36,14 +36,11 @@ def _determine_main(ctx):
 
     main_files = [src for src in ctx.files.srcs if _path_endswith(src.short_path, proposed_main)]
 
-    ###
     # Deviation from logic in rules_python: rules_py is a bit more permissive.
-    # Allow a srcs of length one to determine the main, if the target name didn't
+    # Allow a srcs of length one to determine the main, if the target name didn't match anything.
     if not main_files and len(ctx.files.srcs) == 1:
         main_files = ctx.files.srcs
 
-    ### End deviations
-
     if not main_files:
         if ctx.attr.main:
             fail("could not find '{}' as specified by 'main' attribute".format(proposed_main))
@@ -70,7 +67,8 @@ def _determine_main(ctx):
 
 # Adapts the function above, which we copied from rules_python, to be a standalone rule so we can
 # use it from a macro.
-# (We want our underlying py_binary rule to be simple: 'main' is a mandatory label)
+# This is because we want our underlying py_binary rule to be simple: 'main' is a mandatory label.
+# The default output of this rule will be used as that label.
 def _determine_main_impl(ctx):
     return DefaultInfo(files = depset([_determine_main(ctx)]))
 
@@ -89,7 +87,7 @@ determine_main = rule(
     implementation = _determine_main_impl,
     attrs = {
         "target_name": attr.string(mandatory = True, doc = "The name of the py_binary or py_test we are finding a main for"),
-        "main": attr.string("Hint the user supplied as the main"),
+        "main": attr.string(doc = "Hint the user supplied as the main"),
         "srcs": attr.label_list(allow_files = True),
     },
 )