Add documentation on WORKSPACE methods for repo users

Author: roleroz

bazel/deps.bzl

@@ -1,12 +1,19 @@
 load("@bazel_tools//tools/build_defs/repo:git.bzl", "git_repository")
 load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
 
+# Load the main dependencies from platformio_rules
+#
+# This cannot load all the dependencies, as some load()s are needed from these,
+# which cannot be done in a function, but this is the first step of the process
 def platformio_rules_dependencies():
+    # Import Stardoc, to write the documentation to our Starlark rules
     git_repository(
         name = "io_bazel_stardoc",
         remote = "https://github.com/bazelbuild/stardoc.git",
         tag = "0.5.3",
     )
+    # Import python, this is the first step to get pip_parse() dependencies to
+    # be corrently imported
     http_archive(
         name = "rules_python",
         sha256 = "81cbfc16dd1c022c4761267fa8b2feb881aaea9c3e1143f2e64630a1ad18c347",

bazel/pip_install.bzl

@@ -1,4 +1,6 @@
 load("@py_deps//:requirements.bzl", "install_deps")
 
+# Finally, now that pip_parse() has been executed, install the pip dependencies
 def platformio_rules_pip_install_dependencies():
+    # Install all pip dependencies
     install_deps()

bazel/pip_parse.bzl

@@ -1,7 +1,10 @@
 load("@python3_10_8//:defs.bzl", "interpreter")
 load("@rules_python//python:pip.bzl", "pip_parse")
 
+# Now that Python has been registered, load the pip packages that are required
+# for template rendering
 def platformio_rules_pip_parse_dependencies():
+    # Load the pip packages needed
     pip_parse(
         name = "py_deps",
         python_interpreter_target = interpreter,

bazel/transitive.bzl

@@ -1,8 +1,16 @@
 load("@io_bazel_stardoc//:setup.bzl", "stardoc_repositories")
 load("@rules_python//python:repositories.bzl", "python_register_toolchains")
 
+# Load the first level of dependencies that are based on the ones imported in
+# platformio_rules_dependencies(), as these imports depend on load() commands
+# that come from those imports
 def platformio_rules_transitive_dependencies():
+    # Import all the dependencies for Stardoc, so we can write documentation for
+    # our Starlark rules
     stardoc_repositories()
+
+    # Select the Python toolchain that will be used for template rendering. This
+    # is required for pip_parse() to be executed
     python_register_toolchains(
         name = "python3_10_8",
         # Available versions are listed in @rules_python//python:versions.bzl.