oharboe
commented
4 weeks ago Learning bazel is out of scope for the bazel-orfs documentation, it should start with the assumption that the developer is fairly fluent in the bazel concepts. Enough to hack with github copilot/chatgpt provided it is reviwed by humans afterwards.
This is what github copilot generated... If this is adequate, then I don't think we should add the documentation. I think source code should be viewed through "AI documentation glasses" and then the source code should have some comments and code written such that an AI can come up with something that reasonably describes it.
What is missing from the documentation below you think?
"""Generates and runs a Makefile-based build process for a given stage.
This function sets up the necessary environment and files for running a
Makefile-based build process. It ensures that all required directories and
files are created, and it constructs the appropriate shell command to
execute the build.
Args:
ctx: The rule context, providing access to attributes, actions, and other
build-related information.
stage (str): The name of the build stage.
steps (list): A list of steps to be passed as arguments to the Makefile.
result_names (list, optional): A list of result file names to be generated
by the build process. Defaults to an empty list.
object_names (list, optional): A list of object file names to be generated
by the build process. Defaults to an empty list.
log_names (list, optional): A list of log file names to be generated by the
build process. Defaults to an empty list.
report_names (list, optional): A list of report file names to be generated
by the build process. Defaults to an empty list.
extra_arguments (dict, optional): Additional arguments to be passed to the
Makefile. Defaults to an empty dictionary.
Returns:
A list of providers, including DefaultInfo, OutputGroupInfo, OrfsDepInfo,
OrfsInfo, and other relevant information for the build process.
"""
For Bazel newbies, it would be helpful to add docstring documentation to the code in openroad.bzl to explain what the code is doing. This is especially important for important methods like _make_impl, which is long and does many things.