Merge pull request #11909 from chef/docs_improvements

Improve docs generation + update property / action descriptions

6 files changed, 15 insertions, 18 deletions

diff --git a/lib/chef/provider/execute.rb b/lib/chef/provider/execute.rb
index b4020b8620..bd199f2574 100644
--- a/lib/chef/provider/execute.rb
+++ b/lib/chef/provider/execute.rb
@@ -41,7 +41,7 @@ class Chef
         end
       end
 
-      action :run do
+      action :run, description: "Run a command." do
         if creates && sentinel_file.exist?
           logger.debug("#{new_resource} sentinel file #{sentinel_file} exists - nothing to do")
           return false
diff --git a/lib/chef/provider/launchd.rb b/lib/chef/provider/launchd.rb
index b8ff9dfa4d..a737cd08de 100644
--- a/lib/chef/provider/launchd.rb
+++ b/lib/chef/provider/launchd.rb
@@ -43,22 +43,22 @@ class Chef
         types[type]
       end
 
-      action :create do
+      action :create, description: "Create a launchd property list." do
         manage_plist(:create)
       end
 
-      action :create_if_missing do
+      action :create_if_missing, description: "Create a launchd property list, if it does not already exist." do
         manage_plist(:create_if_missing)
       end
 
-      action :delete do
+      action :delete, description: "Delete a launchd property list. This will unload a daemon or agent, if loaded." do
         if ::File.exists?(path)
           manage_service(:disable)
         end
         manage_plist(:delete)
       end
 
-      action :enable do
+      action :enable, description: "Create a launchd property list, and then ensure that it is enabled. If a launchd property list already exists, but does not match, updates the property list to match, and then restarts the daemon or agent." do
         manage_service(:nothing)
         manage_plist(:create) do
           notifies :restart, "macosx_service[#{label}]", :immediately
@@ -66,13 +66,13 @@ class Chef
         manage_service(:enable)
       end
 
-      action :disable do
+      action :disable, description: "Disable a launchd property list." do
         return unless ::File.exist?(path)
 
         manage_service(:disable)
       end
 
-      action :restart do
+      action :restart, description: "Restart a launchd managed daemon or agent." do
         manage_service(:restart)
       end
 
diff --git a/lib/chef/resource/inspec_waiver_file_entry.rb b/lib/chef/resource/inspec_waiver_file_entry.rb
index fb433edb28..5f81be73da 100644
--- a/lib/chef/resource/inspec_waiver_file_entry.rb
+++ b/lib/chef/resource/inspec_waiver_file_entry.rb
@@ -84,13 +84,13 @@ class Chef
         }
 
       property :run_test, [true, false],
-        description: "If present and true, the control will run and be reported, but failures in it won’t make the overall run fail. If absent or false, the control will not be run."
+        description: "If present and `true`, the control will run and be reported, but failures in it won’t make the overall run fail. If absent or `false`, the control will not be run."
 
       property :justification, String,
         description: "Can be any text you want and might include a reason for the waiver as well as who signed off on the waiver."
 
       property :backup, [false, Integer],
-        description: "The number of backups to be kept in /var/chef/backup (for UNIX- and Linux-based platforms) or C:/chef/backup (for the Microsoft Windows platform). Set to false to prevent backups from being kept.",
+        description: "The number of backups to be kept in `/var/chef/backup` (for UNIX- and Linux-based platforms) or `C:/chef/backup` (for the Microsoft Windows platform). Set to `false` to prevent backups from being kept.",
         default: false
 
       action :add do
diff --git a/lib/chef/resource/launchd.rb b/lib/chef/resource/launchd.rb
index c8e3d93afc..d5be5f3a44 100644
--- a/lib/chef/resource/launchd.rb
+++ b/lib/chef/resource/launchd.rb
@@ -36,7 +36,7 @@ class Chef
 
       property :backup, [Integer, FalseClass],
         desired_state: false,
-        description: "The number of backups to be kept in /var/chef/backup. Set to false to prevent backups from being kept."
+        description: "The number of backups to be kept in `/var/chef/backup`. Set to `false` to prevent backups from being kept."
 
       property :cookbook, String,
         desired_state: false,
@@ -197,10 +197,10 @@ class Chef
         description: "The intended purpose of the job: `Adaptive`, `Background`, `Interactive`, or `Standard`."
 
       property :program, String,
-        description: "The first argument of execvp, typically the file name associated with the file to be executed. This value must be specified if program_arguments is not specified, and vice-versa."
+        description: "The first argument of `execvp`, typically the file name associated with the file to be executed. This value must be specified if `program_arguments` is not specified, and vice-versa."
 
       property :program_arguments, Array,
-        description: "The second argument of execvp. If program is not specified, this property must be specified and will be handled as if it were the first argument."
+        description: "The second argument of `execvp`. If program is not specified, this property must be specified and will be handled as if it were the first argument."
 
       property :queue_directories, Array,
         description: "An array of non-empty directories which, if any are modified, will cause a job to be started."
diff --git a/lib/chef/resource/remote_file.rb b/lib/chef/resource/remote_file.rb
index 8eca1c3337..18f182f40c 100644
--- a/lib/chef/resource/remote_file.rb
+++ b/lib/chef/resource/remote_file.rb
@@ -85,7 +85,7 @@ class Chef
       end
 
       property :use_etag, [ TrueClass, FalseClass ], default: true,
-        description: "Enable ETag headers. Set to false to disable ETag headers. To use this setting, `use_conditional_get` must also be set to true."
+        description: "Enable ETag headers. Set to `false` to disable ETag headers. To use this setting, `use_conditional_get` must also be set to true."
 
       alias :use_etags :use_etag
 
diff --git a/tasks/docs.rb b/tasks/docs.rb
index d12d88130c..2fd92cc40e 100755
--- a/tasks/docs.rb
+++ b/tasks/docs.rb
@@ -35,8 +35,6 @@ namespace :docs_site do
       text = ""
       text << "#{resource_name} 'name' do\n"
       properties.each do |p|
-        next if p["name"] == "sensitive" # we don't need to document sensitive twice
-
         pretty_default = pretty_default(p["default"])
 
         text << "  #{p["name"].ljust(padding_size)}"
@@ -80,6 +78,7 @@ namespace :docs_site do
     def friendly_property_list(arr)
       return nil if arr.empty? # resources w/o properties
 
+      # create an array of backticked property names for use in markdown.
       props = arr.map { |x| "`#{x["name"]}`" }
 
       # build the text string containing all properties bolded w/ punctuation
@@ -142,8 +141,6 @@ namespace :docs_site do
     # @todo what to do about "lazy default" for default?
     def properties_list(properties)
       properties.filter_map do |property|
-        next if property["name"] == "sensitive" # we don't need to document sensitive twice
-
         default_val = friendly_default_value(property)
 
         values = {}
@@ -261,7 +258,7 @@ namespace :docs_site do
 
     # the main method that builds what will become the yaml file
     def build_resource_data(name, data)
-      properties = data["properties"].reject { |v| v["name"] == "name" || v["deprecated"] }.sort_by! { |v| v["name"] }
+      properties = data["properties"].reject { |v| %w{name sensitive}.include?(v["name"]) || v["deprecated"] }.sort_by! { |v| v["name"] }
 
       r = {}