diff options
author | Tim Smith <tsmith@chef.io> | 2018-11-13 22:08:22 -0800 |
---|---|---|
committer | Tim Smith <tsmith@chef.io> | 2018-11-20 14:09:48 -0800 |
commit | 656e641a175f28734703b1f2dbf020785f641325 (patch) | |
tree | 2e068d190fa6db9f3657a6a0b60a4fa153420ee5 /lib | |
parent | 6db3916c7bed81df3c069aa4f307b0c5c0e5f0b5 (diff) | |
download | chef-656e641a175f28734703b1f2dbf020785f641325.tar.gz |
Improve resource descriptions for documentation
Mostly cleaning up how we describe name properties, but also copying over some edits that happened on the docs site.
Signed-off-by: Tim Smith <tsmith@chef.io>
Diffstat (limited to 'lib')
-rw-r--r-- | lib/chef/resource/apt_package.rb | 2 | ||||
-rw-r--r-- | lib/chef/resource/apt_preference.rb | 2 | ||||
-rw-r--r-- | lib/chef/resource/apt_repository.rb | 2 | ||||
-rw-r--r-- | lib/chef/resource/chocolatey_config.rb | 2 | ||||
-rw-r--r-- | lib/chef/resource/chocolatey_source.rb | 2 | ||||
-rw-r--r-- | lib/chef/resource/cron_access.rb | 2 | ||||
-rw-r--r-- | lib/chef/resource/cron_d.rb | 16 | ||||
-rw-r--r-- | lib/chef/resource/dmg_package.rb | 18 | ||||
-rw-r--r-- | lib/chef/resource/execute.rb | 2 | ||||
-rw-r--r-- | lib/chef/resource/homebrew_cask.rb | 2 | ||||
-rw-r--r-- | lib/chef/resource/homebrew_tap.rb | 2 | ||||
-rw-r--r-- | lib/chef/resource/hostname.rb | 4 | ||||
-rw-r--r-- | lib/chef/resource/kernel_module.rb | 2 | ||||
-rw-r--r-- | lib/chef/resource/link.rb | 2 | ||||
-rw-r--r-- | lib/chef/resource/ohai_hint.rb | 2 | ||||
-rw-r--r-- | lib/chef/resource/package.rb | 2 |
16 files changed, 32 insertions, 32 deletions
diff --git a/lib/chef/resource/apt_package.rb b/lib/chef/resource/apt_package.rb index 3f4a36489d..e55d37fcc8 100644 --- a/lib/chef/resource/apt_package.rb +++ b/lib/chef/resource/apt_package.rb @@ -32,7 +32,7 @@ class Chef property :overwrite_config_files, [TrueClass, FalseClass], introduced: "14.0", - description: "Overwrite existing config files with those in the package if prompted by apt.", + description: "Overwrite existing configuration files with those supplied by the package, if prompted by APT.", default: false end diff --git a/lib/chef/resource/apt_preference.rb b/lib/chef/resource/apt_preference.rb index 7ece829ba2..caa0f01305 100644 --- a/lib/chef/resource/apt_preference.rb +++ b/lib/chef/resource/apt_preference.rb @@ -30,7 +30,7 @@ class Chef property :package_name, String, name_property: true, - description: "The name of the package.", + description: "An optional property to set the package name if it differs from the resource block's name.", regex: [/^([a-z]|[A-Z]|[0-9]|_|-|\.|\*|\+)+$/], validation_message: "The provided package name is not valid. Package names can only contain alphanumeric characters as well as _, -, +, or *!" diff --git a/lib/chef/resource/apt_repository.rb b/lib/chef/resource/apt_repository.rb index 9a7632cde9..145b515a41 100644 --- a/lib/chef/resource/apt_repository.rb +++ b/lib/chef/resource/apt_repository.rb @@ -34,7 +34,7 @@ class Chef # to allow that so don't refactor this however tempting it is property :repo_name, String, regex: [/^[^\/]+$/], - description: "The name of the repository to configure, if it differs from the name of the resource block. The value of this setting must not contain spaces.", + description: "An optional property to set the repository name if it differs from the resource block's name. The value of this setting must not contain spaces.", validation_message: "repo_name property cannot contain a forward slash '/'", introduced: "14.1", name_property: true diff --git a/lib/chef/resource/chocolatey_config.rb b/lib/chef/resource/chocolatey_config.rb index e9452e8f3c..10e133594f 100644 --- a/lib/chef/resource/chocolatey_config.rb +++ b/lib/chef/resource/chocolatey_config.rb @@ -24,7 +24,7 @@ class Chef introduced "14.3" property :config_key, String, name_property: true, - description: "The name of the config. The resource's name will be used if this isn't provided." + description: "An optional property to set the config key name if it differs from the resource block's name." property :value, String, description: "The value to set." diff --git a/lib/chef/resource/chocolatey_source.rb b/lib/chef/resource/chocolatey_source.rb index 5319f82ab4..a2db254603 100644 --- a/lib/chef/resource/chocolatey_source.rb +++ b/lib/chef/resource/chocolatey_source.rb @@ -24,7 +24,7 @@ class Chef introduced "14.3" property :source_name, String, name_property: true, - description: "The name of the source to add. The resource's name will be used if this isn't provided." + description: "An optional property to set the source name if it differs from the resource block's name." property :source, String, description: "The source URL." diff --git a/lib/chef/resource/cron_access.rb b/lib/chef/resource/cron_access.rb index b6b822ba40..8f43ed1891 100644 --- a/lib/chef/resource/cron_access.rb +++ b/lib/chef/resource/cron_access.rb @@ -31,7 +31,7 @@ class Chef description "Use the cron_access resource to manage the /etc/cron.allow and /etc/cron.deny files." property :user, String, - description: "The user to allow or deny. If not provided we'll use the resource name.", + description: "An optional property to set the user name if it differs from the resource block's name.", name_property: true action :allow do diff --git a/lib/chef/resource/cron_d.rb b/lib/chef/resource/cron_d.rb index 6beff4936e..baa05ca58e 100644 --- a/lib/chef/resource/cron_d.rb +++ b/lib/chef/resource/cron_d.rb @@ -88,7 +88,7 @@ class Chef end property :cron_name, String, - description: "Set the name of the cron job. If this isn't specified we'll use the resource name.", + description: "An optional property to set the cron name if it differs from the resource block's name.", name_property: true property :cookbook, String, desired_state: false @@ -98,31 +98,31 @@ class Chef equal_to: %w{ @reboot @yearly @annually @monthly @weekly @daily @midnight @hourly } property :minute, [Integer, String], - description: "The minute to schedule the cron job to run at. Valid values: 0-59.", + description: "The minute at which the cron entry should run (0 - 59).", default: "*", callbacks: { "should be a valid minute spec" => ->(spec) { validate_numeric(spec, 0, 59) }, } property :hour, [Integer, String], - description: "The hour to schedule the cron job to run at. Valid values: 0-23.", + description: "The hour at which the cron entry is to run (0 - 23).", default: "*", callbacks: { "should be a valid hour spec" => ->(spec) { validate_numeric(spec, 0, 23) }, } property :day, [Integer, String], - description: "The day to schedule the cron job to run at. Valid values: 1-31.", + description: "The day of month at which the cron entry should run (1 - 31).", default: "*", callbacks: { "should be a valid day spec" => ->(spec) { validate_numeric(spec, 1, 31) }, } property :month, [Integer, String], - description: "The month to schedule the cron job to run at. Valid values: 1-12, jan-dec, or *.", + description: "The month in the year on which a cron entry is to run (1 - 12, jan-dec, or *).", default: "*", callbacks: { "should be a valid month spec" => ->(spec) { validate_month(spec) }, } property :weekday, [Integer, String], - description: "The day to schedule the cron job to run at. Valid values: 0-7, mon-sun, or *.", + description: "The day of the week on which this entry is to run (0-7, mon-sun, or *), where Sunday is both 0 and 7.", default: "*", callbacks: { "should be a valid weekday spec" => ->(spec) { validate_dow(spec) }, } @@ -132,7 +132,7 @@ class Chef required: true property :user, String, - description: "The user to run the cron job as.", + description: "The name of the user that runs the command.", default: "root" property :mailto, String, @@ -151,7 +151,7 @@ class Chef description: "A comment to place in the cron.d file." property :environment, Hash, - description: "A Hash containing additional arbitrary environment variables under which the cron job will be run.", + description: "A Hash containing additional arbitrary environment variables under which the cron job will be run in the form of ``({'ENV_VARIABLE' => 'VALUE'})``. (These variables must exist for a command to be run successfully.)", default: lazy { Hash.new } property :mode, [String, Integer], diff --git a/lib/chef/resource/dmg_package.rb b/lib/chef/resource/dmg_package.rb index cd2f0b5c3a..93dfd524b8 100644 --- a/lib/chef/resource/dmg_package.rb +++ b/lib/chef/resource/dmg_package.rb @@ -27,31 +27,31 @@ class Chef introduced "14.0" property :app, String, - description: "The name of the application used by default for the /Volumes directory and the .app directory copied to /Applications.", + description: "The name of the application as it appears in the /Volumes directory, if it differs from the resource block name.", name_property: true property :source, String, - description: "The remote URL for the dmg to download if specified." + description: "The remote URL that is used to download the .dmg file, if specified." property :file, String, - description: "The local dmg full file path." + description: "The full path to the .dmg file on the local system." property :owner, String, - description: "The owner that should own the package installation." + description: "The user that should own the package installation." property :destination, String, description: "The directory to copy the .app into.", default: "/Applications" property :checksum, String, - description: "The sha256 checksum of the dmg to download." + description: "The sha256 checksum of the .dmg file to download." property :volumes_dir, String, - description: "The Directory under /Volumes where the dmg is mounted as not all dmgs are mounted into a /Volumes location matching the name of the dmg.", + description: "The directory under /Volumes where the dmg is mounted, if it differs from the name of the .dmg file.", default: lazy { |r| r.app }, default_description: "The value passed for the application name." property :dmg_name, String, - description: "The name of the dmg if it is not the same as app, or if the name has spaces.", + description: "The name of the .dmg file if it differs from that of the app, or if the name has spaces.", desired_state: false, default: lazy { |r| r.app }, default_description: "The value passed for the application name." @@ -61,10 +61,10 @@ class Chef default: "app", desired_state: false property :package_id, String, - description: "The package id registered with pkgutil when a pkg or mpkg is installed." + description: "The package ID that is registered with pkgutil when a pkg or mpkg is installed." property :dmg_passphrase, String, - description: "Specify a passphrase to use to unencrypt the dmg while mounting.", + description: "Specify a passphrase to be used to decrypt the .dmg file during the mount process.", desired_state: false property :accept_eula, [TrueClass, FalseClass], diff --git a/lib/chef/resource/execute.rb b/lib/chef/resource/execute.rb index e74d0c1439..e2f389325e 100644 --- a/lib/chef/resource/execute.rb +++ b/lib/chef/resource/execute.rb @@ -65,7 +65,7 @@ class Chef description: "The current working directory from which the command will be run." property :environment, Hash, - description: "Specify a Hash of environment variables to be set." + description: "A Hash of environment variables in the form of ({'ENV_VARIABLE' => 'VALUE'}). (These variables must exist for a command to be run successfully.)" alias :env :environment diff --git a/lib/chef/resource/homebrew_cask.rb b/lib/chef/resource/homebrew_cask.rb index 7c47fbbfcd..71b40c55bf 100644 --- a/lib/chef/resource/homebrew_cask.rb +++ b/lib/chef/resource/homebrew_cask.rb @@ -32,7 +32,7 @@ class Chef include Chef::Mixin::HomebrewUser property :cask_name, String, - description: "The name of the Homebrew cask, if it differs from the resource block name.", + description: "An optional property to set the cask name if it differs from the resource block's name.", regex: %r{^[\w/-]+$}, validation_message: "The provided Homebrew cask name is not valid. Cask names can contain alphanumeric characters, _, -, or / only!", name_property: true diff --git a/lib/chef/resource/homebrew_tap.rb b/lib/chef/resource/homebrew_tap.rb index a4591e9ed8..aff65685b7 100644 --- a/lib/chef/resource/homebrew_tap.rb +++ b/lib/chef/resource/homebrew_tap.rb @@ -32,7 +32,7 @@ class Chef include Chef::Mixin::HomebrewUser property :tap_name, String, - description: "Optional tap name to override the resource name", + description: "An optional property to set the tap name if it differs from the resource block's name.", validation_message: "Homebrew tap names must be in the form REPO/TAP format!", regex: %r{^[\w-]+(?:\/[\w-]+)+$}, name_property: true diff --git a/lib/chef/resource/hostname.rb b/lib/chef/resource/hostname.rb index 37106efd74..89c4c0c6d0 100644 --- a/lib/chef/resource/hostname.rb +++ b/lib/chef/resource/hostname.rb @@ -27,7 +27,7 @@ class Chef introduced "14.0" property :hostname, String, - description: "Used to specify the hostname if it is different than the resource's name.", + description: "An optional property to set the hostnam if it differs from the resource block's name.", name_property: true property :compile_time, [ TrueClass, FalseClass ], @@ -36,7 +36,7 @@ class Chef property :ipaddress, String, description: "The IP address to use when configuring the hosts file.", - default: lazy { node["ipaddress"] } + default: lazy { node["ipaddress"] }, default_description: "The node's IP address as determined by Ohai." property :aliases, [ Array, nil ], description: "An array of hostname aliases to use when configuring the hosts file.", diff --git a/lib/chef/resource/kernel_module.rb b/lib/chef/resource/kernel_module.rb index ea33d19ff1..0f2053334e 100644 --- a/lib/chef/resource/kernel_module.rb +++ b/lib/chef/resource/kernel_module.rb @@ -18,7 +18,7 @@ class Chef introduced "14.3" property :modname, String, - description: "The name of the kernel module.", + description: "An optional property to set the kernel module name if it differs from the resource block's name.", name_property: true, identity: true property :load_dir, String, diff --git a/lib/chef/resource/link.rb b/lib/chef/resource/link.rb index 00ce69dddd..45d1e3011a 100644 --- a/lib/chef/resource/link.rb +++ b/lib/chef/resource/link.rb @@ -48,7 +48,7 @@ class Chef end property :target_file, String, - description: "The name of the link. Default value: the name of the resource block.", + description: "An optional property to set the target file if it differs from the resource block's name.", name_property: true, identity: true property :to, String, diff --git a/lib/chef/resource/ohai_hint.rb b/lib/chef/resource/ohai_hint.rb index d1b538c70f..0a710a166c 100644 --- a/lib/chef/resource/ohai_hint.rb +++ b/lib/chef/resource/ohai_hint.rb @@ -27,7 +27,7 @@ class Chef introduced "14.0" property :hint_name, String, - description: "The name of the hints file, if it differs from the resource name.", + description: "An optional property to set the hint name if it differs from the resource block's name.", name_property: true property :content, Hash, diff --git a/lib/chef/resource/package.rb b/lib/chef/resource/package.rb index 2a94ca6c02..670671e22b 100644 --- a/lib/chef/resource/package.rb +++ b/lib/chef/resource/package.rb @@ -42,7 +42,7 @@ class Chef end property :package_name, [ String, Array ], - description: "The name of the package. Defaults to the name of the resourse block unless specified.", + description: "An optional property to set the package name if it differs from the resource block's name.", identity: true property :version, [ String, Array ], |