Document policy builder API on the dynamic builder

1 files changed, 56 insertions, 0 deletions

diff --git a/lib/chef/policy_builder/dynamic.rb b/lib/chef/policy_builder/dynamic.rb
index deefd1e855..c9842ba532 100644
--- a/lib/chef/policy_builder/dynamic.rb
+++ b/lib/chef/policy_builder/dynamic.rb
@@ -57,6 +57,11 @@ class Chef
 
       # Loads the node state from the server, then picks the correct
       # implementation class based on the node and json_attribs.
+      #
+      # Calls #finish_load_node on the implementation object to complete the
+      # loading process. All subsequent lifecycle calls are delegated.
+      #
+      # @return [Chef::Node] the loaded node.
       def load_node
         events.node_load_start(node_name, config)
         Chef::Log.debug("Building node object for #{node_name}")
@@ -77,21 +82,72 @@ class Chef
 
       ## Delegated Public API Methods ##
 
+      ### Accessors ###
+
       def_delegator :implementation, :original_runlist
       def_delegator :implementation, :run_context
       def_delegator :implementation, :run_list_expansion
+
+      ### Lifecycle Methods ###
+
+      # @!method build_node
+      #
+      # Applies external attributes (e.g., from JSON file, environment,
+      # policyfile, etc.) and determines the correct expanded run list for the
+      # run.
+      #
+      # @return [Chef::Node]
       def_delegator :implementation, :build_node
+
+      # @!method setup_run_context
+      #
+      # Synchronizes cookbooks and initializes the run context object for the
+      # run.
+      #
+      # @return [Chef::RunContext]
       def_delegator :implementation, :setup_run_context
+
+      # @!method expanded_run_list
+      #
+      # Resolves the run list to a form containing only recipes and sets the
+      # `roles` and `recipes` automatic attributes on the node.
+      #
+      # @return [#recipes, #roles] A RunListExpansion or duck-type.
       def_delegator :implementation, :expand_run_list
+
+      # @!method sync_cookbooks
+      #
+      # Synchronizes cookbooks. In a normal chef-client run, this is handled by
+      # #setup_run_context, but may be called directly in some circumstances.
+      #
+      # @return [Hash{String => Chef::CookbookManifest}] A map of
+      #   CookbookManifest objects by cookbook name.
       def_delegator :implementation, :sync_cookbooks
+
+      # @!method temporary_policy?
+      #
+      # Indicates whether the policy is temporary, which means an
+      # override_runlist was provided. Chef::Client uses this to decide whether
+      # to do the final node save at the end of the run or not.
+      #
+      # @return [true,false]
       def_delegator :implementation, :temporary_policy?
 
       ## Internal Public API ##
 
+      # Returns the selected implementation, or raises if not set. The
+      # implementation is set when #load_node is called.
+      #
+      # @return [PolicyBuilder::Policyfile, PolicyBuilder::ExpandNodeObject]
       def implementation
         @implementation or raise Exceptions::InvalidPolicybuilderCall, "#load_node must be called before other policy builder methods"
       end
 
+      # @api private
+      #
+      # Sets the implementation based on the content of the node, node JSON
+      # (i.e., the `-j JSON_FILE` data), and config. This is only public for
+      # testing purposes; production code should call #load_node instead.
       def select_implementation(node)
         if policyfile_set_in_config? ||
             policyfile_attribs_in_node_json? ||