# HG changeset patch
# User Jan Heylen <heyleke@gmail.com>
# Date 1430370318 -7200
# Node ID 34f2da0a2969a1e5ba72e92e00366cb1b1f5ce18
# Parent  71140b7c9abfcb34db70792c39e09a4e4796efb1
ChangesetCommentsModel: cleanup of doc strings

Docstrings that are out of date is a bug. Docstrings that doesn't add any value
is thus a liability we would like to get rid of.

[Changeset extracted and modified by Mads Kiilerich.]

diff -r 71140b7c9abf -r 34f2da0a2969 kallithea/model/comment.py
--- a/kallithea/model/comment.py	Wed Apr 29 04:25:53 2015 +0200
+++ b/kallithea/model/comment.py	Thu Apr 30 07:05:18 2015 +0200
@@ -63,10 +63,6 @@
                                line_no=None, revision=None, pull_request=None,
                                status_change=None, closing_pr=False):
         """
-        Get notification data
-
-        :param comment_text:
-        :param line:
         :returns: tuple (subj,body,recipients,notification_type,email_kwargs)
         """
         # make notification
@@ -167,20 +163,10 @@
                f_path=None, line_no=None, status_change=None, closing_pr=False,
                send_email=True):
         """
-        Creates new comment for changeset or pull request.
-        If status_change is not None this comment is associated with a
-        status change of changeset or changesets associated with pull request
+        Creates a new comment for either a changeset or a pull request.
+        status_change and closing_pr is only for the optional email.
 
-        :param text:
-        :param repo:
-        :param user:
-        :param revision:
-        :param pull_request: (for emails, not for comments)
-        :param f_path:
-        :param line_no:
-        :param status_change: (for emails, not for comments)
-        :param closing_pr: (for emails, not for comments)
-        :param send_email: also send email
+        Returns the created comment.
         """
         if not status_change and not text:
             log.warning('Missing text for comment, skipping...')
@@ -239,11 +225,6 @@
         return comment
 
     def delete(self, comment):
-        """
-        Deletes given comment
-
-        :param comment_id:
-        """
         comment = self.__get_changeset_comment(comment)
         Session().delete(comment)
 
@@ -251,13 +232,10 @@
 
     def get_comments(self, repo_id, revision=None, pull_request=None):
         """
-        Gets main comments based on revision or pull_request_id
+        Gets general comments for either revision or pull_request.
 
-        :param repo_id:
-        :param revision:
-        :param pull_request:
+        Returns a list, ordered by creation date.
         """
-
         q = ChangesetComment.query()\
                 .filter(ChangesetComment.repo_id == repo_id)\
                 .filter(ChangesetComment.line_no == None)\
@@ -273,6 +251,11 @@
         return q.all()
 
     def get_inline_comments(self, repo_id, revision=None, pull_request=None):
+        """
+        Gets inline comments for either revision or pull_request.
+
+        Returns a list of tuples with file path and list of comments per line number.
+        """
         q = Session().query(ChangesetComment)\
             .filter(ChangesetComment.repo_id == repo_id)\
             .filter(ChangesetComment.line_no != None)\