Document all the libraries

.inch.yml

@@ -0,0 +1,26 @@
+files:
+  included:
+    - Berksfile
+    - Gemfile
+    - Guardfile
+    - Rakefile
+    - attributes/*.rb
+    - definitions/*.rb
+    - libraries/*.rb
+    - providers/*.rb
+    - recipes/*.rb
+    - resources/*.rb
+    - templates/**/*.rb
+    - spec/**/*.rb
+    - test/**/*.rb
+    - metatada.rb
+    - Gemfile
+    - Rakefile
+    - Capfile
+    - Guardfile
+    - Podfile
+    - Thorfile
+    - Vagrantfile
+    - Berksfile
+    - Cheffile
+    - Vagabondfile

.yardopts

@@ -0,0 +1,5 @@
+--markup markdown
+--no-private
+'*/**/*.rb'
+-
+*.md

README.md

@@ -6,6 +6,7 @@ ownCloud Cookbook
 [![Code Climate](http://img.shields.io/codeclimate/github/zuazo/owncloud-cookbook.svg?style=flat)](https://codeclimate.com/github/zuazo/owncloud-cookbook)
 [![Build Status](http://img.shields.io/travis/zuazo/owncloud-cookbook.svg?style=flat)](https://travis-ci.org/zuazo/owncloud-cookbook)
 [![Coverage Status](http://img.shields.io/coveralls/zuazo/owncloud-cookbook.svg?style=flat)](https://coveralls.io/r/zuazo/owncloud-cookbook?branch=master)
+[![Inline docs](http://inch-ci.org/github/zuazo/owncloud-cookbook.svg?branch=master&style=flat)](http://inch-ci.org/github/zuazo/owncloud-cookbook)
 
 [Chef](https://www.chef.io/) cookbook to install and configure [ownCloud](http://owncloud.org/), an open source personal cloud for data and file sync, share and view.
 

TODO.md

@@ -1,4 +1,4 @@
 TODO
 ====
 
-* [ ] Document the libraries.
+* [ ] ...

libraries/config.rb

@@ -25,9 +25,24 @@
 # `owncloud` cookbook internal classes.
 module OwncloudCookbook
   # Class to read and write ownCloud configuration file.
+  #
+  # @example
+  #   config_file = '/var/www/owncloud/config/config.php'
+  #   c = OwncloudCookbook::Config.new(config_file)
+  #   c.merge(node['owncloud']['config'])
+  #   c.write
   class Config
     attr_reader :options
 
+    # OwncloudCookbook::Config constructor.
+    #
+    # Reads the current configuration values.
+    #
+    # @param file [String] ownCloud PHP configuration file path.
+    # @example
+    #   config_file = '/var/www/owncloud/config/config.php'
+    #   OwncloudCookbook::Config.new(config_file)
+    # @api public
     def initialize(file)
       @file = file
       @options = {}
@@ -37,15 +52,37 @@ def initialize(file)
 
     protected
 
+    # Returns the configuration options in PHP compatible JSON format as
+    # string.
+    #
+    # @return [String] The JSON string.
+    # @example
+    #   @options = Hash.new
+    #   @options['key'] = "valu'e"
+    #   options_php_json #=> "{\"key\":\"valu\\'e\"}"
+    # @private
     def options_php_json
       @options.to_json.gsub('\\', '\\\\\\').gsub("'", "\\\\'")
     end
 
+    # Merge two option values.
+    #
+    # Makes an union on array values.
+    #
+    # It also mantains the original dbtype when sqlite3 driver is available.
+    #
+    # @param key [String] configuration key name.
+    # @param value1 [Mixed] the original value.
+    # @param value2 [Mixed] the new value.
+    # @return [Mixed] the configuration values merged.
+    # @example
+    #   merge_value('key', 'A', 'B') #=> "B"
+    #   merge_value('array', %w(1 2), %w(2 3)) #=> ["1", "2", "3"]
+    #   merge_value('dbtype', 'sqlite3', 'sqlite') #=> "sqlite3"
+    # @private
     def merge_value(key, value1, value2)
-      # make an union on array values
       if value1.is_a?(Array) && value2.is_a?(Array)
         value1 | value2
-      # exotic case: mantain original dbtype when sqlite3 driver is available
       elsif key == 'dbtype' && value1 == 'sqlite3' && value2 == 'sqlite'
         value1
       else
@@ -55,10 +92,32 @@ def merge_value(key, value1, value2)
 
     public
 
+    # Gets an option value.
+    #
+    # @param index [Mixed] option name.
+    # @return [Mixed] option value.
+    # @example
+    #   config_file = '/var/www/owncloud/config/config.php'
+    #   c = OwncloudCookbook::Config.new(config_file)
+    #   c['dbtype'] #=> 'mysql'
+    # @api public
     def [](index)
       @options[index]
     end
 
+    # Merges new configuration options with the current values.
+    #
+    # Saves the merged configuration values internally in an accumulator
+    # variable but not on disk.
+    #
+    # @param new_options [Hash] New configuration values.
+    # @return [Hash] Merged configuration values.
+    # @example
+    #   config_file = '/var/www/owncloud/config/config.php'
+    #   c = OwncloudCookbook::Config.new(config_file)
+    #   c.merge(node['owncloud']['config'])
+    #     #=> {"dbtype"=>"mysql", "dbname"=>"owncloud", ...}
+    # @api public
     def merge(new_options)
       return unless new_options.respond_to?(:to_hash)
       new_options = new_options.to_hash
@@ -68,6 +127,17 @@ def merge(new_options)
       @options.merge!(new_options) { |k, v1, v2| merge_value(k, v1, v2) }
     end
 
+    # Reads the current configuration values from disk.
+    #
+    # Saves the read configuration values internally in an accumulator
+    # variable.
+    #
+    # @return [Hash] Configuration values.
+    # @example
+    #   config_file = '/var/www/owncloud/config/config.php'
+    #   c = OwncloudCookbook::Config.new(config_file)
+    #   c.read #=> {"dbtype"=>"mysql", "dbname"=>"owncloud", ...}
+    # @api public
     def read
       return unless ::File.exist?(@file)
       f = IO.popen('php', 'r+')
@@ -81,6 +151,9 @@ def read
       raise "Error reading ownCloud configuration: #{e.message}"
     end
 
+    # Writes the accumulated configuration values to disk.
+    #
+    # @return void
     def write
       return if @options == @original_options
       f = IO.popen('php', 'r+')

libraries/cookbook_helpers.rb

@@ -22,26 +22,68 @@
 # `owncloud` cookbook internal classes.
 module OwncloudCookbook
   # Some helpers to use from `owncloud` cookbook recipes or resources.
+  #
+  # @example
+  #   self.class.send(:include, OwncloudCookbook::CookbookHelpers)
+  #   apply_owncloud_configuration
   module CookbookHelpers
+    # Gets the ownCloud configuration file full path.
+    #
+    # @return [String] configuration file path.
+    # @example
+    #   owncloud_config_file #=> '/var/www/owncloud/config/config.php'
+    # @api public
     def owncloud_config_file
       ::File.join(node['owncloud']['dir'], 'config', 'config.php')
     end
 
+    # Returns the [OwncloudCookbook::Config] instance.
+    #
+    # @return [OwncloudCookbook::Config] configuration object.
+    # @example
+    #   owncloud_config #=> #<OwncloudCookbook::Config:0x00000001b637c0>
+    # @api public
     def owncloud_config
       @owncloud_config ||= OwncloudCookbook::Config.new(owncloud_config_file)
     end
 
+    # Gets ownCloud default configuration values.
+    #
+    # @return [Hash] configuration values.
+    # @example
+    #   owncloud_cookbook_config
+    #     #=> {"dbtype"=>"mysql", "dbname"=>"owncloud", ...}
+    # @api public
     def owncloud_cookbook_config
       @owncloud_cookbook_config ||= node['owncloud']['config'].to_hash
     end
 
+    # Generates the ownCloud trusted domain list.
+    #
+    # Generates the domain list from the `node['owncloud']['server_name']` and
+    # the `node['owncloud']['server_aliases']` attribute values.
+    #
+    # @return [Array] domain list.
+    # @example
+    #   owncloud_trusted_domains #=> ["owncloud.example.com"]
+    # @api public
     def owncloud_trusted_domains
       [
         node['owncloud']['server_name'], node['owncloud']['server_aliases']
       ].flatten
     end
 
-    # Add server name and server aliases to trusted_domains config option.
+    # Adds server name and server aliases to trusted_domains configuration
+    # option.
+    #
+    # Merges the generated owncloud trusted domains and the
+    # `node['owncloud']['config']['trusted_domains']` attribute values.
+    #
+    # @return [Array] domain list.
+    # @example
+    #   calculate_trusted_domains
+    #     #=> ["owncloud.example.com", "www.example.com"]
+    # @api public
     def calculate_trusted_domains
       unless owncloud_cookbook_config.key?('trusted_domains')
         owncloud_cookbook_config['trusted_domains'] = []
@@ -52,27 +94,59 @@ def calculate_trusted_domains
       end
     end
 
+    # Calculates the database host.
+    #
+    # @return [String] database host and port.
+    # @example
+    #   calculate_dbhost #=> "db.example.com:3306"
+    # @api public
     def calculate_dbhost
       owncloud_cookbook_config['dbhost'] =
         [
           owncloud_cookbook_config['dbhost'], owncloud_cookbook_config['dbport']
         ].join(':')
     end
 
+    # Updates the disk configuration values from the new calculated values.
+    #
+    # Merges all the configuration values.
+    #
+    # @return void
+    # @example
+    #   owncloud_config_update
+    # @api public
     def owncloud_config_update
       owncloud_config.merge(owncloud_cookbook_config)
       owncloud_config.write
       owncloud_config
     end
 
     # Store important options that where generated automatically by the setup.
+    #
+    # Saves them in Chef Node attributes.
+    #
+    # @return void
+    # @example
+    #   save_owncloud_node_configuration
+    # @api public
     def save_owncloud_node_configuration
       return if Chef::Config[:solo]
       %w(passwordsalt instanceid).each do |value|
         node.set_unless['owncloud']['config'][value] = owncloud_config[value]
       end
     end
 
+    # Calculates new configuration options, merged them and save them on disk.
+    #
+    # - Calculates trusted domains.
+    # - Calculates database host.
+    # - Updates ownCloud configuration options on disk.
+    # - Saves some generated options in Chef Node attributes.
+    #
+    # @return void
+    # @example
+    #   apply_owncloud_configuration
+    # @api public
     def apply_owncloud_configuration
       calculate_trusted_domains
       calculate_dbhost

test/unit/support/cookbook_stubs.rb

@@ -18,12 +18,32 @@
 #
 
 if defined?(ChefSpec)
+  # ChefSpec stubs for `apache2` cookbook.
+  #
+  # @return void
+  # @example
+  #   describe 'mycookbook::default' do
+  #     let(:chef_runner) { ChefSpec::SoloRunner.new }
+  #     let(:chef_run) { chef_runner.converge(described_recipe) }
+  #     before { stub_apache2_cookbook }
+  #     # [...]
+  #   end
   def stub_apache2_cookbook
     stub_command('/usr/sbin/apache2 -t').and_return(true)
     stub_command('/usr/sbin/httpd -t').and_return(true)
     stub_command('which php').and_return(true)
   end
 
+  # ChefSpec stubs for `php-fpm` cookbook.
+  #
+  # @return void
+  # @example
+  #   describe 'mycookbook::default' do
+  #     let(:chef_runner) { ChefSpec::SoloRunner.new }
+  #     let(:chef_run) { chef_runner.converge(described_recipe) }
+  #     before { stub_php_fpm_cookbook }
+  #     # [...]
+  #   end
   def stub_php_fpm_cookbook
     stub_command(
       'test -d /etc/php5/fpm/pool.d || mkdir -p /etc/php5/fpm/pool.d'
@@ -32,12 +52,32 @@ def stub_php_fpm_cookbook
       .and_return(true)
   end
 
+  # ChefSpec stubs for `nginx` cookbook.
+  #
+  # @return void
+  # @example
+  #   describe 'mycookbook::default' do
+  #     let(:chef_runner) { ChefSpec::SoloRunner.new }
+  #     let(:chef_run) { chef_runner.converge(described_recipe) }
+  #     before { stub_nginx_cookbook }
+  #     # [...]
+  #   end
   def stub_nginx_cookbook
     stub_php_fpm_cookbook
     stub_command('which nginx').and_return(true)
     allow(::File).to receive(:symlink?).and_call_original
   end
 
+  # ChefSpec stubs for `postgresql` cookbook.
+  #
+  # @return void
+  # @example
+  #   describe 'mycookbook::default' do
+  #     let(:chef_runner) { ChefSpec::SoloRunner.new }
+  #     let(:chef_run) { chef_runner.converge(described_recipe) }
+  #     before { stub_postgresql_cookbook }
+  #     # [...]
+  #   end
   def stub_postgresql_cookbook
     stub_command(
       "psql -c 'SELECT lanname FROM pg_catalog.pg_language' #{db_name} "\
@@ -50,6 +90,16 @@ def stub_postgresql_cookbook
       .and_return(true)
   end
 
+  # ChefSpec stubs for `postfix` cookbook.
+  #
+  # @return void
+  # @example
+  #   describe 'mycookbook::default' do
+  #     let(:chef_runner) { ChefSpec::SoloRunner.new }
+  #     let(:chef_run) { chef_runner.converge(described_recipe) }
+  #     before { stub_postfix_cookbook }
+  #     # [...]
+  #   end
   def stub_postfix_cookbook
     stub_command(
       '/usr/bin/test /etc/alternatives/mta -ef /usr/sbin/sendmail.postfix'

test/unit/support/matchers.rb

@@ -18,6 +18,11 @@
 #
 
 if defined?(ChefSpec)
+  # ChefSpec matcher for MySQL services `:start` action.
+  #
+  # @return void
+  # @example
+  #   expect(chef_run).to start_mysql_service('default')
   def start_mysql_service(resource_name)
     ChefSpec::Matchers::ResourceMatcher.new(
       :mysql_service, :start, resource_name