jro_apps/redmine Commit - r2536:c2dfffd7f267

Added some RDoc documentation for some models....

Eric Davis -

r2536:c2dfffd7f267

parent child

Context file:

r2536:c2dfffd7f267

Collapse all files

app/models/issue.rb +10 0

                  recipients.compact.uniq
                end
+               # Returns the total number of hours spent on this issue.
+               #
+               # Example:
+               #   spent_hours => 0
+               #   spent_hours => 50
                def spent_hours
                  @spent_hours ||= time_entries.sum(:hours) || 0
                end
                  due_date || (fixed_version ? fixed_version.effective_date : nil)
                end
+               # Returns the time scheduled for this issue.
+               #
+               # Example:
+               #   Start Date: 2/26/09, End Date: 3/04/09
+               #   duration => 6
                def duration
                  (start_date && due_date) ? due_date - start_date : 0
                end

app/models/mailer.rb +46 -2

                  { :host => h, :protocol => Setting.protocol }
                end
+               # Builds a tmail object used to email recipients of the added issue.
+               #
+               # Example:
+               #   issue_add(issue) => tmail object
+               #   Mailer.deliver_issue_add(issue) => sends an email to issue recipients
                def issue_add(issue)
                  redmine_headers 'Project' => issue.project.identifier,
                                  'Issue-Id' => issue.id,
                       :issue_url => url_for(:controller => 'issues', :action => 'show', :id => issue)
                end
+               # Builds a tmail object used to email recipients of the edited issue.
+               #
+               # Example:
+               #   issue_edit(journal) => tmail object
+               #   Mailer.deliver_issue_edit(journal) => sends an email to issue recipients
                def issue_edit(journal)
                  issue = journal.journalized
                  redmine_headers 'Project' => issue.project.identifier,
                       :issues_url => url_for(:controller => 'issues', :action => 'index', :set_filter => 1, :assigned_to_id => user.id, :sort_key => 'due_date', :sort_order => 'asc')
                end
+               # Builds a tmail object used to email users belonging to the added document's project.
+               #
+               # Example:
+               #   document_added(document) => tmail object
+               #   Mailer.deliver_document_added(document) => sends an email to the document's project recipients
                def document_added(document)
                  redmine_headers 'Project' => document.project.identifier
                  recipients document.project.recipients
                       :document_url => url_for(:controller => 'documents', :action => 'show', :id => document)
                end
+               # Builds a tmail object used to email recipients of a project when an attachements are added.
+               #
+               # Example:
+               #   attachments_added(attachments) => tmail object
+               #   Mailer.deliver_attachments_added(attachments) => sends an email to the project's recipients
                def attachments_added(attachments)
                  container = attachments.first.container
                  added_to = ''
                       :added_to => added_to,
                       :added_to_url => added_to_url
                end
+               # Builds a tmail object used to email recipients of a news' project when a news item is added.
+               #
+               # Example:
+               #   news_added(news) => tmail object
+               #   Mailer.deliver_news_added(news) => sends an email to the news' project recipients
                def news_added(news)
                  redmine_headers 'Project' => news.project.identifier
                  message_id news
                       :news_url => url_for(:controller => 'news', :action => 'show', :id => news)
                end
+               # Builds a tmail object used to email the specified recipients of the specified message that was posted.
+               #
+               # Example:
+               #   message_posted(message, recipients) => tmail object
+               #   Mailer.deliver_message_posted(message, recipients) => sends an email to the recipients
                def message_posted(message, recipients)
                  redmine_headers 'Project' => message.project.identifier,
                                  'Topic-Id' => (message.parent_id || message.id)
                       :message_url => url_for(:controller => 'messages', :action => 'show', :board_id => message.board_id, :id => message.root)
                end
+               # Builds a tmail object used to email the specified user their account information.
+               #
+               # Example:
+               #   account_information(user, password) => tmail object
+               #   Mailer.deliver_account_information(user, password) => sends account information to the user
                def account_information(user, password)
                  set_language_if_valid user.language
                  recipients user.mail
                       :login_url => url_for(:controller => 'account', :action => 'login')
                end
+               # Builds a tmail object used to email all active administrators of an account activation request.
+               #
+               # Example:
+               #   account_activation_request(user) => tmail object
+               #   Mailer.deliver_account_activation_request(user)=> sends an email to all active administrators
                def account_activation_request(user)
                  # Send the email to all active administrators
                  recipients User.active.find(:all, :conditions => {:admin => true}).collect { |u| u.mail }.compact
                       :url => url_for(:controller => 'users', :action => 'index', :status => User::STATUS_REGISTERED, :sort_key => 'created_on', :sort_order => 'desc')
                end
-               # A registered user's account was activated by an administrator
+               # Builds a tmail object used to email the specified user that their account was activated by an administrator.
+               #
+               # Example:
+               #   account_activated(user) => tmail object
+               #   Mailer.deliver_account_activated(user) => sends an email to the registered user
                def account_activated(user)
                  set_language_if_valid user.language
                  recipients user.mail

app/models/project.rb +15 -1

                  find(:all, :limit => count, :conditions => visible_by(user), :order => "created_on DESC")
                end
+               # Returns a SQL :conditions string used to find all active projects for the specified user.
+               #
+               # Examples:
+               #     Projects.visible_by(admin)        => "projects.status = 1"
+               #     Projects.visible_by(normal_user)  => "projects.status = 1 AND projects.is_public = 1"
                def self.visible_by(user=nil)
                  user ||= User.current
                  if user && user.admin?
                  end
                  statements.empty? ? base_statement : "((#{base_statement}) AND (#{statements.join(' OR ')}))"
                end
+               # Returns a :conditions SQL string that can be used to find the issues associated with this project.
+               #
+               # Examples:
+               #   project.project_condition(true)  => "(projects.id = 1 OR (projects.lft > 1 AND projects.rgt < 10))"
+               #   project.project_condition(false) => "projects.id = 1"
                def project_condition(with_subprojects)
                  cond = "#{Project.table_name}.id = #{id}"
                  cond = "(#{cond} OR (#{Project.table_name}.lft > #{lft} AND #{Project.table_name}.rgt < #{rgt}))" if with_subprojects
                  description.gsub(/^(.{#{length}}[^\n\r]*).*$/m, '\1...').strip if description
                end
+               # Return true if this project is allowed to do the specified action.
+               # action can be:
+               # * a parameter-like Hash (eg. :controller => 'projects', :action => 'edit')
+               # * a permission Symbol (eg. :edit_project)
                def allows_to?(action)
                  if action.is_a? Hash
                    allowed_actions.include? "#{action[:controller]}/#{action[:action]}"

app/models/user.rb +2 0

                  @current_user ||= User.anonymous
                end
+               # Returns the anonymous user.  If the anonymous user does not exist, it is created.  There can be only
+               # one anonymous user per database.
                def self.anonymous
                  anonymous_user = AnonymousUser.find(:first)
                  if anonymous_user.nil?

app/models/version.rb +12 -2

                  effective_date && (effective_date <= Date.today) && (open_issues_count == 0)
                end
+               # Returns the completion percentage of this version based on the amount of open/closed issues
+               # and the time spent on the open issues.
                def completed_pourcent
                  if issues_count == 0
 
                  end
                end
+               # Returns the percentage of issues that have been marked as 'closed'.
                def closed_pourcent
                  if issues_count == 0
 
                  @issue_count ||= fixed_issues.count
                end
+               # Returns the total amount of open issues for this version.
                def open_issues_count
                  @open_issues_count ||= Issue.count(:all, :conditions => ["fixed_version_id = ? AND is_closed = ?", self.id, false], :include => :status)
                end
+               # Returns the total amount of closed issues for this version.
                def closed_issues_count
                  @closed_issues_count ||= Issue.count(:all, :conditions => ["fixed_version_id = ? AND is_closed = ?", self.id, true], :include => :status)
                end
                  @estimated_average
                end
-               # Returns the total progress of open or closed issues
+               # Returns the total progress of open or closed issues.  The returned percentage takes into account
+               # the amount of estimated time set for this version.
+               #
+               # Examples:
+               # issues_progress(true)   => returns the progress percentage for open issues.
+               # issues_progress(false)  => returns the progress percentage for closed issues.
                def issues_progress(open)
                  @issues_progress ||= {}
                  @issues_progress[open] ||= begin
                    progress = 0
                    if issues_count > 0
                      ratio = open ? 'done_ratio' : 100
                      done = fixed_issues.sum("COALESCE(estimated_hours, #{estimated_average}) * #{ratio}",
                                                :include => :status,
                                                :conditions => ["is_closed = ?", !open]).to_f
                      progress = done / (estimated_average * issues_count)
                    end
                    progress

General Comments 0

Write
Preview

You need to be logged in to leave comments. Login now

No TODOs yet

	Site-wide shortcuts
/	Use quick search box
g h	Goto home page
g g	Goto my private gists page
g G	Goto my public gists page
g 0-9	Goto bookmarked items from 0-9
n r	New repository page
n g	New gist page

	Repositories
g s	Goto summary page
g c	Goto changelog page
g f	Goto files page
g F	Goto files page with file search activated
g p	Goto pull requests page
g o	Goto repository settings
g O	Goto repository access permissions settings
t s	Toggle sidebar on some pages