More helpers

app/helpers/markdown_tools_helper.rb

@@ -1,4 +1,23 @@
 module MarkdownToolsHelper
+  ##
+  # Create a Markdown tool button.
+  # @param name [String] A name to display on the button. If you want to use an icon instead, pass a block and leave
+  #   +name+ as +nil+ (default).
+  # @param action [String] Populates the button's +data-action+ attribute, which can be processed later via Markdown JS.
+  # @param label [String] Populates the button's +title+ and +aria-label+ attributes.
+  # @param attribs [Hash{#to_s => Object}] A hash of additional attributes to pass to the tag generator.
+  # @yieldparam context [ActionView::Helpers::TagHelper::TagBuilder]
+  # @yieldreturn [String, ActiveSupport::SafeBuffer]
+  # @return [ActiveSupport::SafeBuffer]
+  # @example Create a Bold button with icon:
+  #   <%= md_button action: 'bold', label: 'Bold', data: { index: 1 } do %>
+  #     <i class="fas fa-bold"></i>
+  #   <% end %>
+  #
+  #   # => <a class="button is-muted is-outlined js-markdown-tool" data-action="bold" data-index="1" aria-label="Bold"
+  #           role="button">
+  #          <i class="fas fa-bold"></i>
+  #        </a>
   def md_button(name = nil, action: nil, label: nil, **attribs, &block)
     attribs.merge! href: 'javascript:void(0)',
                    class: "#{attribs[:class] || ''} button is-muted is-outlined js-markdown-tool",
@@ -14,6 +33,11 @@ def md_button(name = nil, action: nil, label: nil, **attribs, &block)
     end
   end
 
+  # Create a Markdown tool list item. Identical to
+  # @param (see #md_button)
+  # @yieldparam (see #md_button)
+  # @yieldreturn (see #md_button)
+  # @return (see #md_button)
   def md_list_item(name = nil, action: nil, label: nil, **attribs, &block)
     attribs.merge! href: 'javascript:void(0)',
                    class: "#{attribs[:class] || ''}js-markdown-tool",

app/helpers/moderator_helper.rb

@@ -1,5 +1,14 @@
 # Provides helper methods for use by views under <tt>ModeratorController</tt>.
 module ModeratorHelper
+  ##
+  # Display text on a specified background color.
+  # @param cls [String] The background color class.
+  # @param content [String] The text to display. For uses beyond simple text, pass a block instead.
+  # @option opts :class [String] Additional classes to add to the element. For instance, if the background color is dark,
+  #   consider passing a class for a light text color.
+  # @yieldparam context [ActionView::Helpers::TagHelper::TagBuilder]
+  # @yieldreturn [ActiveSupport::SafeBuffer, String]
+  # @return [ActiveSupport::SafeBuffer]
   def text_bg(cls, content = nil, **opts, &block)
     if block_given?
       tag.span class: ["has-background-color-#{cls}", opts[:class]].join(' '), &block

app/helpers/post_types_helper.rb

@@ -1,14 +1,41 @@
 module PostTypesHelper
+  ##
+  # Create a badge to display the specified post type.
+  # @param type [PostType]
+  # @return [ActiveSupport::SafeBuffer]
   def post_type_badge(type)
     tag.span class: 'badge is-tag is-filled is-muted' do
-      tag.i(class: type.icon_name) + ' ' + tag.span(type.name) # rubocop:disable Style/StringConcatenation
+      "#{tag.i(class: type.icon_name)} #{tag.span(type.name)}"
     end
   end
 
+  ##
+  # Get a list of predicate post type attributes (i.e. is_* and has_* attributes).
+  # @api private
+  # @return [Array<Symbol>]
   def post_type_criteria
     PostType.new.attributes.keys.select { |k| k.start_with?('has_') || k.start_with?('is_') }.map(&:to_sym)
   end
 
+  ##
+  # Get a list of post type IDs matching specified criteria. Available criteria are based on predicate attributes on the
+  # post_types table (i.e. +has_*+ and +is_*+ attributes).
+  # @option opts :has_answers [Boolean]
+  # @option opts :has_votes [Boolean]
+  # @option opts :has_tags [Boolean]
+  # @option opts :has_parent [Boolean]
+  # @option opts :has_category [Boolean]
+  # @option opts :has_license [Boolean]
+  # @option opts :is_public_editable [Boolean]
+  # @option opts :is_closeable [Boolean]
+  # @option opts :is_top_level [Boolean]
+  # @option opts :is_freely_editable [Boolean]
+  # @option opts :has_reactions [Boolean]
+  # @option opts :has_only_specific_reactions [Boolean]
+  # @return [Array<Integer>]
+  # @example Query for IDs of top-level post types which are freely editable and have reactions:
+  #   helpers.post_type_ids(is_top_level: true, is_freely_editable: true, has_reactions: true)
+  #   # => [12, 23, 49]
   def post_type_ids(**opts)
     key = post_type_criteria.map { |a| opts[a] ? '1' : '0' }.join
     Rails.cache.fetch "network/post_types/post_type_ids/#{key}", include_community: false do