Add or update some API docs

Some functions were undocumented, some of them had wrong docs or
typos, some of them needed a small update in docs after the
reload-on-configuration-change work.

Signed-off-by: Lorenzo Manacorda <lorenzo@kinvolk.io>

components/sup/src/manager/mod.rs

@@ -667,6 +667,7 @@ impl Manager {
         }
     }
 
+    // Creates a rumor for the specified service.
     fn gossip_latest_service_rumor(&self, service: &Service) {
         let mut incarnation = 1;
         {

components/sup/src/manager/service/config.rs

@@ -139,7 +139,7 @@ impl Cfg {
     /// Updates the service configuration with data from a census group if the census group has
     /// newer data than the current configuration.
     ///
-    /// Returns true if the configuration was updated.
+    /// Returns `true` if the configuration was updated.
     pub fn update(&mut self, census_group: &CensusGroup) -> bool {
         match census_group.service_config {
             Some(ref config) => {
@@ -260,6 +260,7 @@ impl Cfg {
         Self::load_toml_file(path, USER_CONFIG_FILE)
     }
 
+    /// Reloads the user configuration file.
     pub fn reload_user(&mut self) -> Result<()> {
         let user = Self::load_user(&self.user_config_path)?;
         self.user = user;
@@ -351,6 +352,7 @@ impl Serialize for Cfg {
 }
 
 #[derive(Debug)]
+/// Renders configuration templates into config files.
 pub struct CfgRenderer(TemplateRenderer);
 
 impl CfgRenderer {
@@ -388,6 +390,8 @@ impl CfgRenderer {
     }
 
     /// Compile and write all configuration files to the configuration directory.
+    ///
+    /// Returns `true` if the configuration has changed.
     pub fn compile(&self, pkg: &Pkg, ctx: &RenderContext) -> Result<bool> {
         // JW TODO: This function is loaded with IO errors that will be converted a Supervisor
         // error resulting in the end-user not knowing what the fuck happned at all. We need to go

components/sup/src/manager/service/hooks.rs

@@ -98,6 +98,8 @@ pub trait Hook: fmt::Debug + Sized {
     fn new(service_group: &ServiceGroup, render_pair: RenderPair) -> Self;
 
     /// Compile a hook into its destination service directory.
+    ///
+    /// Returns `true` if the hook has changed.
     fn compile(&self, service_group: &ServiceGroup, ctx: &RenderContext) -> Result<bool> {
         let content = self.renderer().render(Self::file_name(), ctx)?;
         if write_hook(&content, self.path())? {

components/sup/src/manager/service/mod.rs

@@ -263,6 +263,7 @@ impl Service {
         }
     }
 
+    /// Runs the reconfigure hook if present, otherwise restarts the service.
     fn reload(&mut self, launcher: &LauncherCli) {
         self.needs_reload = false;
         if self.process_down() || self.hooks.reload.is_none() {
@@ -291,6 +292,9 @@ impl Service {
         self.supervisor.state_entered
     }
 
+    /// Performs updates and executes hooks.
+    ///
+    /// Returns `true` if the service was updated.
     pub fn tick(&mut self, census_ring: &CensusRing, launcher: &LauncherCli) -> bool {
         if !self.initialized {
             if !self.all_binds_satisfied(census_ring) {
@@ -409,10 +413,10 @@ impl Service {
         self.supervisor.state == ProcessState::Down
     }
 
-    /// Compares the current state of the service to the current state of the census ring and
-    /// re-renders all templatable content to disk.
+    /// Compares the current state of the service to the current state of the census ring and the
+    /// user-config, and re-renders all templatable content to disk.
     ///
-    /// Returns true if any modifications were made.
+    /// Returns `true` if any modifications were made.
     fn update_templates(&mut self, census_ring: &CensusRing) -> bool {
         let census_group = census_ring.census_group_for(&self.service_group).expect(
             "Service update failed; unable to find own service group",
@@ -452,7 +456,7 @@ impl Service {
         cfg_changed
     }
 
-    /// Replace the package of the running service and restart it's system process.
+    /// Replace the package of the running service and restart its system process.
     pub fn update_package(&mut self, package: PackageInstall, launcher: &LauncherCli) {
         match Pkg::from_install(package) {
             Ok(pkg) => {
@@ -507,7 +511,7 @@ impl Service {
         rumor
     }
 
-    /// Run initialization hook if present
+    /// Run initialization hook if present.
     fn initialize(&mut self) {
         if self.initialized {
             return;
@@ -523,8 +527,7 @@ impl Service {
         }
     }
 
-    /// Run reconfigure hook if present. Return false if it is not present, to trigger default
-    /// restart behavior.
+    /// Run reconfigure hook if present.
     fn reconfigure(&mut self) {
         self.needs_reconfiguration = false;
         if let Some(ref hook) = self.hooks.reconfigure {
@@ -617,6 +620,8 @@ impl Service {
     }
 
     /// Helper for compiling configuration templates into configuration files.
+    ///
+    /// Returns `true` if the configuration has changed.
     fn compile_configuration(&self, ctx: &RenderContext) -> bool {
         match self.config_renderer.compile(&self.pkg, ctx) {
             Ok(true) => {
@@ -636,6 +641,8 @@ impl Service {
     /// Helper for compiling hook templates into hooks.
     ///
     /// This function will also perform any necessary post-compilation tasks.
+    ///
+    /// Returns `true` if any hooks have changed.
     fn compile_hooks(&self, ctx: &RenderContext) -> bool {
         let changed = self.hooks.compile(&self.service_group, ctx);
         if let Some(err) = self.copy_run().err() {
@@ -699,13 +706,14 @@ impl Service {
             if self.needs_reload || self.process_down() || self.needs_reconfiguration {
                 self.reload(launcher);
                 if self.needs_reconfiguration {
+                    // NOTE this only runs the hook if it's defined
                     self.reconfigure()
                 }
             }
         }
     }
 
-    /// Run file_updated hook if present
+    /// Run file_updated hook if present.
     fn file_updated(&self) -> bool {
         if self.initialized {
             if let Some(ref hook) = self.hooks.file_updated {
@@ -719,9 +727,11 @@ impl Service {
         false
     }
 
-    /// Write service files from gossip data to disk.
+    /// Write service files from gossip data to disk under
+    /// [`svc_files_path()`](../../fs/fn.svc_files_path.html).
     ///
-    /// Returns true if a file was changed, added, or removed, and false if there were no updates.
+    /// Returns `true` if a file was changed, added, or removed, and
+    /// `false` if there were no updates.
     fn update_service_files(&mut self, census_ring: &CensusRing) -> bool {
         let census_group = census_ring.census_group_for(&self.service_group).expect(
             "Service update service files failed; unable to find own service group",
@@ -782,11 +792,13 @@ impl Service {
         self.cache_health_check(check_result);
     }
 
+    // Returns `false` if the write fails.
     fn cache_service_file(&mut self, service_file: &ServiceFile) -> bool {
         let file = self.pkg.svc_files_path.join(&service_file.filename);
         self.write_cache_file(file, &service_file.body)
     }
 
+    // Returns `false` if the write fails.
     fn write_cache_file<T>(&self, file: T, contents: &[u8]) -> bool
     where
         T: AsRef<Path>,

components/sup/src/manager/service_updater.rs

@@ -62,6 +62,9 @@ enum FollowerState {
     Updating(Receiver<PackageInstall>),
 }
 
+/// The ServiceUpdater is in charge of updating a Service when a more recent version of a package
+/// has been published to a depot or installed to the local package cache.
+/// To use an update strategy, the supervisor must be configured to watch a depot for new versions.
 pub struct ServiceUpdater {
     states: UpdaterStateList,
     butterfly: butterfly::Server,

components/sup/src/templating/context.rs

@@ -53,6 +53,9 @@ impl<'a> BindGroup<'a> {
     }
 }
 
+/// The context of a render call.
+///
+/// It stores information on a Service and its configuration.
 #[derive(Clone, Debug, Serialize)]
 pub struct RenderContext<'a> {
     pub sys: &'a Sys,