Document classes and methods, as part of the template rendering documentation review

Author: bgandon

src/bosh-director-core/lib/bosh/director/core/templates/job_instance_renderer.rb

@@ -3,12 +3,39 @@
 require 'bosh/director/formatter_helper'
 
 module Bosh::Director::Core::Templates
+
+  # @param [Array<DeploymentPlan::Job>] instance_jobs
+  # @param [JobTemplateLoader] job_template_loader
   class JobInstanceRenderer
     def initialize(templates, job_template_loader)
       @templates = templates
       @job_template_loader = job_template_loader
     end
 
+    # Render all templates for a Bosh instance.
+    #
+    # From a list of instance jobs (typically comming from a single instance
+    # plan, so they cover all templates of some instance) this method is
+    # responsible for orchestrating several tasks.
+    #
+    # Lazily-delegated work to a 'JobTemplateLoader' object:
+    #   - Load all templates of the release job that the instance job is
+    #     referring to
+    #   - Convert each of these to a 'JobTemplateRenderer' object
+    #
+    # Work done here on top of this:
+    #   - Render each template with the necessary bindings (comming from
+    #     deployment manifest properties) for building the special 'spec'
+    #     object that the ERB rendring code can use.
+    #
+    # The actual rendering of each template is delegated to its related
+    # 'JobTemplateRenderer' object, as created in the first place by the
+    # 'JobTemplateLoader' object.
+    #
+    # @param [Hash] spec_object A hash of properties that will finally result
+    #                           in the `spec` object exposed to ERB templates
+    # @return [RenderedJobInstance] An object containing the rendering results
+    #                               (when successful)
     def render(spec)
       errors = []
 

src/bosh-director-core/lib/bosh/director/core/templates/job_template_loader.rb

@@ -15,6 +15,24 @@ def initialize(logger, template_blob_cache, link_provider_intents, dns_encoder)
         @dns_encoder = dns_encoder
       end
 
+      # Perform these operations in order:
+      #
+      #  1. Download (or fetch from cache) a single job blob tarball.
+      #
+      #  2. Extract the job blob tarball in a temporary directory.
+      #
+      #  3. Access the extracted 'job.MF' manifest from the job blob.
+      #
+      #  4. Load all ERB templates (including the 'monit' file and all other
+      #     declared files within the 'templates' subdir) and create one
+      #     'SourceErb' object for each of these.
+      #
+      #  5. Create and return a 'JobTemplateRenderer' object, populated with
+      #     all created 'SourceErb' objects.
+      #
+      # @param [DeploymentPlan::Job] instance_job The job whose templates
+      #                                           should be rendered
+      # @return [JobTemplateRenderer] Object that can render the templates
       def process(job_template)
         template_dir = extract_template(job_template)
         manifest = Psych.load_file(File.join(template_dir, 'job.MF'), aliases: true)

src/bosh-director/lib/bosh/director/config_server/variables_interpolator.rb

@@ -7,10 +7,19 @@ def initialize
       @cache_by_job_name = {}
     end
 
-    # @param [Hash] template_spec_properties Hash to be interpolated
-    # @param [Hash] deployment_name The deployment context in-which the interpolation will occur
-    # @param [VariableSet] variable_set The variable set which the interpolation will use.
-    # @return [Hash] A Deep copy of the interpolated template_spec_properties
+    # From a `job_name => job_properties` hash of instance group properties,
+    # resolve the `((var_name))`` placeholders, fetching their values from the
+    # config server. Most often, these placeholders refers to secrets stored
+    # in CredHub.
+    #
+    # @param [Hash] instance_group_properties a hash of per-job properties, to
+    #                                         be interpolated
+    # @param [String] deployment_name The name of the deployment, as context
+    #                                 in-which the interpolation will occur
+    # @param [String] instance_group_name The name of the instance group
+    # @param [VariableSet] variable_set The variable set which the
+    #                                   interpolation will use.
+    # @return [Hash] A Deep copy of the interpolated instance_group_properties
     def interpolate_template_spec_properties(template_spec_properties, deployment_name, instance_name, variable_set)
       if template_spec_properties.nil?
         return template_spec_properties

src/bosh-director/lib/bosh/director/deployment_plan/instance_group.rb

@@ -409,10 +409,19 @@ def create_desired_instances(count, deployment)
 
       private
 
+      # Returns the aggregated list of package names, considering all jobs
+      # desired on this instance group, with no duplicate.
+      #
+      # @return [Array<String>] The list of package names
       def run_time_dependencies
         run_time_packages.map(&:name)
       end
 
+      # The aggregated list of models for all packages to install on instances
+      # of the group, considering all jobs desired on this instance group,
+      # with no duplicate.
+      #
+      # @return [Array<Models::Package>] The list of packages
       def run_time_packages
         jobs.flat_map(&:package_models).uniq
       end

src/bosh-director/lib/bosh/director/deployment_plan/instance_plan.rb

@@ -379,6 +379,11 @@ def spec
           InstanceSpec.create_from_instance_plan(self)
         end
 
+        # Returns the desired jobs for the instance
+        #
+        # Here “template” is the old Bosh v1 name for “job”.
+        #
+        # @return [Array<DeploymentPlan::Job>] List of desired jobs
         def templates
           @desired_instance.instance_group.jobs
         end

src/bosh-director/lib/bosh/director/deployment_plan/instance_spec.rb

@@ -17,7 +17,7 @@ def self.create_from_instance_plan(instance_plan)
 
         spec = {
           'deployment' => deployment_name,
-          'job' => instance_group.spec,
+          'job' => instance_group.spec, # <- here 'job' is old Bosh v1 naming, meaning 'instance group'
           'index' => instance.index,
           'bootstrap' => instance.bootstrap?,
           'lifecycle' => instance_group.lifecycle,

src/bosh-director/lib/bosh/director/deployment_plan/job.rb

@@ -34,7 +34,10 @@ def initialize(release, name)
         @properties = {}
       end
 
-      # Looks up template model and its package models in DB
+      # Looks up job model and its package models in DB.
+      #
+      # Here “template” is the old Bosh v1 name for “job”.
+      #
       # @return [void]
       def bind_models
         @model = @release.get_template_model_by_name(@name)

src/bosh-director/lib/bosh/director/deployment_plan/release_version.rb

@@ -91,8 +91,11 @@ def spec
         }
       end
 
-      # Looks up up template model by template name
-      # @param [String] name Template name
+      # Looks up up job model by job name.
+      #
+      # Here “template” is the old Bosh v1 name for “job”.
+      #
+      # @param [String] name Job name
       # @return [Models::Template]
       def get_template_model_by_name(name)
         @all_jobs ||= @model.templates.each_with_object({}) do |job, all_jobs|
@@ -109,25 +112,38 @@ def get_package_model_by_name(name)
         @model.package_by_name(name)
       end
 
-      # Adds template to a list of templates used by this release for the
-      # current deployment
+      # Adds a job to a list of jobs used by this release for the current
+      # deployment.
+      #
+      # Here “template” is the old Bosh v1 name for “job”.
+      #
       # @param [String] options Template name
       def get_or_create_template(name)
         @jobs[name] ||= Job.new(self, name)
       end
 
+      # Return a given job, identified by name.
+      #
+      # Here “template” is the old Bosh v1 name for “job”.
+      #
       # @param [String] name Job name
       # @return [DeploymentPlan::Job] Job with given name used by this
-      #   release (if any)
+      #                               release (if any)
       def template(name)
         @jobs[name]
       end
 
-      # Returns a list of job templates that need to be included into this
-      # release. Note that this is not just a list of all templates existing
-      # in the release but rather a list of templates for jobs that are included
-      # into current deployment plan.
-      # @return [Array<DeploymentPlan::Job>] List of job templates
+      # Returns a list of jobs from the release that are used by the
+      # deployment.
+      #
+      # Note that this is not the full list of all jobs existing in the
+      # release, but a subset list of the jobs defined in that release that
+      # are used by the current deployment, and thus included in its plan.
+      #
+      # Here “template” is the old Bosh v1 name for “job”.
+      #
+      # @return [Array<DeploymentPlan::Job>] List of the release jobs used by
+      #                                      the deployment
       def templates
         @jobs.values
       end

src/bosh-director/lib/bosh/director/job_renderer.rb

@@ -4,6 +4,20 @@
 
 module Bosh::Director
   class JobRenderer
+
+    # Render the related job templates for each instance plan passed as
+    # argument in the 'instance_plans' array.
+    #
+    # @param [Logging::Logger] logger A logger where to log activity
+    # @param [Array<InstancePlan>] instance_plans A list of instance plans
+    # @param [TemplateBlobCache] cache A cache through which job blobs are to
+    #                                  be fetched
+    # @param [DnsEncoder] dns_encoder A DNS encoder for generating Bosh DNS
+    #                                 queries out of context and criteria
+    # @param [Array<LinkProviderIntent>] link_provider_intents Relevant
+    #                                                          context-dependant
+    #                                                          link provider
+    #                                                          intents
     def self.render_job_instances_with_cache(logger, instance_plans, cache, dns_encoder, link_provider_intents)
       job_template_loader = Core::Templates::JobTemplateLoader.new(
         logger,
@@ -17,6 +31,15 @@ def self.render_job_instances_with_cache(logger, instance_plans, cache, dns_enco
       end
     end
 
+    # For one instance plan, create a 'JobInstanceRenderer' object that will
+    # lazily load the ERB templates for all desired jobs on the instance, then
+    # render these templates with the bindings populated by the
+    # 'spec' properties of the instance plan.
+    #
+    # @param [DeploymentPlan::InstancePlan] instance_plan An instance plan
+    # @param [JobTemplateLoader] loader The object that will load the ERB
+    #                                   templates
+    # @param [Logging::Logger] logger A logger where to log activity
     def self.render_job_instance(instance_plan, loader, logger)
       instance = instance_plan.instance
 

src/bosh-director/lib/bosh/director/models/template.rb

@@ -1,4 +1,8 @@
 module Bosh::Director::Models
+
+  # This class models a job, as defined within a Bosh Release.
+  #
+  # Here “template” is the old Bosh v1 name for “job”.
   class Template < Sequel::Model(Bosh::Director::Config.db)
     many_to_one :release
     many_to_many :release_versions