added a bunch of YARD comments for methods

Author: Oaphi

app/controllers/application_controller.rb

@@ -318,7 +318,7 @@ def enforce_signed_in
                    path.start_with?('/assets/') ||
                    path.end_with?('.css') || path.end_with?('.js')
 
-    # Make available to controller that the we should not leak posts in the sidebar
+    # Used by derived controllers to avoid leaking featured posts to the sidebar
     @prevent_sidebar = true
 
     # Allow /help (help center), /help/* and /policy/* depending on settings

app/controllers/posts_controller.rb

@@ -725,6 +725,9 @@ def unless_locked
     check_if_locked(@post)
   end
 
+  # Attempts to actually delete a post draft
+  # @param path [String] draft path to delete
+  # @return [Boolean] status of the operation
   def do_draft_delete(path)
     keys = [:body, :comment, :excerpt, :license, :saved_at, :tags, :tag_name, :title].map do |key|
       pfx = key == :saved_at ? 'saved_post_at' : 'saved_post'

app/models/category.rb

@@ -44,6 +44,9 @@ def top_level_post_types
     post_types.where(is_top_level: true)
   end
 
+  # Are there new posts for a given user since their last visit?
+  # @param user [User] user to check
+  # @return [Boolean] check result
   def new_posts_for?(user)
     key = "#{community_id}/#{user.id}/#{id}/last_visit"
     Rails.cache.fetch key, expires_in: 5.minutes do
@@ -72,6 +75,9 @@ def self.accessible_to(user)
     Category.where('IFNULL(min_view_trust_level, -1) <= ?', trust_level)
   end
 
+  # Gets category matching a given name
+  # @param name [String] name of the category
+  # @return [Category, nil]
   def self.by_lowercase_name(name)
     categories = Rails.cache.fetch 'categories/by_lowercase_name' do
       Category.all.to_h { |c| [c.name.downcase, c.id] }
@@ -87,6 +93,9 @@ def self.by_id(id)
     categories[id]
   end
 
+  # Gets a collection of categories matching a given search term
+  # @param term [String] search term
+  # @return [ActiveRecord::Relation<Category>]
   def self.search(term)
     where('name LIKE ?', "%#{sanitize_sql_like(term)}%")
   end

app/models/close_reason.rb

@@ -7,6 +7,8 @@ class CloseReason < ApplicationRecord
                    presence: true,
                    uniqueness: { scope: [:community_id], case_sensitive: false }
 
+  # Is the close reason network-wide (global)?
+  # @return [Boolean] check result
   def global?
     community.nil?
   end

app/models/comment_thread.rb

@@ -16,10 +16,16 @@ class CommentThread < ApplicationRecord
 
   after_create :create_follower
 
+  # Are there any threads on a given post that a given user follows?
+  # @param post [Post] post to check
+  # @param user [User] user to check
+  # @return [Boolean] check result
   def self.post_followed?(post, user)
     ThreadFollower.where(post: post, user: user).any?
   end
 
+  # Is the thread read-only (can't be edited)?
+  # @return [Boolean] check result
   def read_only?
     locked? || archived? || deleted?
   end

app/models/user_ability.rb

@@ -2,6 +2,8 @@ class UserAbility < ApplicationRecord
   belongs_to :community_user
   belongs_to :ability
 
+  # Is the ability temporarily or permanently suspended?
+  # @return [Boolean] check result
   def suspended?
     return true if is_suspended && suspension_end.nil? # permanent suspension
     return true if is_suspended && !suspension_end.past?