Add comments (#74)

for_workspace/cmake_build.bzl

@@ -1,3 +1,5 @@
+""" Rule for building CMake from sources. """
+
 load(":detect_root.bzl", "detect_root")
 
 def _cmake_tool(ctx):
@@ -28,6 +30,10 @@ def _cmake_tool(ctx):
 
     return [DefaultInfo(files = depset([cmake]))]
 
+""" Rule for building CMake. Invokes bootstrap script and make install.
+  Attributes:
+    cmake_srcs - target with the CMake sources
+"""
 cmake_tool = rule(
     attrs = {
         "cmake_srcs": attr.label(mandatory = True),

for_workspace/ninja_build.bzl

@@ -1,3 +1,5 @@
+""" Rule for building Ninja from sources. """
+
 load("//:detect_root.bzl", "detect_root")
 
 def _ninja_tool(ctx):
@@ -23,6 +25,10 @@ def _ninja_tool(ctx):
 
     return [DefaultInfo(files = depset([ninja]))]
 
+""" Rule for building Ninja. Invokes configure script and make install.
+  Attributes:
+    ninja_srcs - target with the Ninja sources
+"""
 ninja_tool = rule(
     attrs = {
         "ninja_srcs": attr.label(mandatory = True),

for_workspace/os_info.bzl

@@ -1,9 +1,13 @@
+""" Rules for host and target operating system information.
+However, just provides very simple information.
+"""
+
 OSInfo = provider(
-    doc = "TODO",
+    doc = "Operating system information.",
     fields = dict(
-        is_win = "",
-        is_osx = "",
-        is_unix = "",
+        is_win = "Is Windows family system",
+        is_osx = "Is Mac family system",
+        is_unix = "Is Unix family system (default)",
     ),
 )
 
@@ -14,6 +18,10 @@ def _os_info_impl(ctx):
     return [DefaultInfo(files = depset([out])), os_info]
 
 def get_os_info(os_name):
+    """ Returns OSInfo provider with the information about operating system.
+      Args:
+        os_name - operating system name in the form returned by repository context
+    """
     is_win = os_name.find("windows") != -1
     is_osx = os_name.startswith("mac os")
     return OSInfo(
@@ -30,6 +38,11 @@ _os_info = rule(
 )
 
 def define_os(host_os_name):
+    """ Macros for creating two rules about host and target operating systems,
+with the names 'host_os' and 'target_os'. Both rules return OSInfo provider.
+  Args:
+    host_os_name - host operating system name in the form returned by repository context
+"""
     _os_info(
         name = "target_os",
         os_name = select({

for_workspace/repositories.bzl

@@ -1,3 +1,5 @@
+""" Remote repositories, used by this project itself """
+
 load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
 
 def repositories():

tools/build_defs/cmake.bzl

@@ -100,9 +100,9 @@ def _attrs():
         })
     return attrs
 
-""" Rule for building external library with CMake
+""" Rule for building external library with CMake.
  Attributes:
-   cmake_options - (list of strings) options to be passed to the cmake call
+   See line comments in _attrs() method.
  Other attributes are documented in framework.bzl:CC_EXTERNAL_RULE_ATTRIBUTES
 """
 cmake_external = rule(

tools/build_defs/cmake_script.bzl

@@ -1,3 +1,5 @@
+""" Contains all logic for calling CMake for building external libraries/binaries """
+
 load("@foreign_cc_platform_utils//:tools.bzl", "CMAKE_COMMAND")
 load(":cc_toolchain_util.bzl", "absolutize_path_in_str")
 
@@ -12,6 +14,20 @@ def create_cmake_script(
         user_cache,
         user_env,
         options):
+    """ Constructs CMake script to be passed to cc_external_rule_impl.
+  Args:
+    workspace_name - current workspace name
+    target_os - OSInfo with target operating system information, used for CMAKE_SYSTEM_NAME in
+CMake toolchain file
+    tools - cc_toolchain tools (CxxToolsInfo)
+    flags - cc_toolchain flags (CxxFlagsInfo)
+    install_prefix - value ot pass to CMAKE_INSTALL_PREFIX
+    root - sources root relative to the $EXT_BUILD_ROOT
+    no_toolchain_file - if False, CMake toolchain file will be generated, otherwise not
+    user_cache - dictionary with user's values of cache initializers
+    user_env - dictionary with user's values for CMake environment variables
+    options - other CMake options specified by user
+"""
     toolchain_dict = _fill_crossfile_from_toolchain(workspace_name, target_os, tools, flags)
     params = None
     if no_toolchain_file:

tools/build_defs/detect_root.bzl

@@ -1,15 +1,8 @@
 def detect_root(source):
     """Detects the path to the topmost directory of the 'source' outputs.
     To be used with external build systems to point to the source code/tools directories.
+"""
 
-    If the target groups the sources of the external dependency, the workspace root is used,
-    and no other checks are performed (i.e. it is assumed that the whole contents of the external
-    dependency is used).
-    Otherwise, for the "usual" targets, target's files are iterated and the path with the least length
-    is selected.
-    """
-
-    #    root = source.label.workspace_root
     root = ""
     sources = source.files
     if (root and len(root) > 0) or len(sources) == 0: