Uploaded image for project: 'Moodle'
  1. Moodle
  2. MDL-30984

comment API, check and update DocBlock

    Details

    • Type: Task
    • Status: Closed
    • Priority: Minor
    • Resolution: Fixed
    • Affects Version/s: 2.2, 2.2.1
    • Fix Version/s: 2.3
    • Component/s: Comments, Documentation
    • Labels:

      Description

      Check and update documentation, so that it should comply with moodle coding guidelines.
      Following needs to be updated/checked for comment api

      1. DocBlock for page and functions.
      2. All the files should be checked/updated.

      Note: You can create sub-tasks, so as to avoid bulk integration.

        Gliffy Diagrams

          Attachments

            Activity

            Hide
            dougiamas Martin Dougiamas added a comment -

            Hi,

            I see "@category comment" in the block etc, this is not part of the API for other plugins.

            Can you remove these? The @category should just be on the functions/classes that other modules (eg mod/database) call, as well as possibly some of the implementations in those modules (as you have done).

            I've moved the old spec to http://docs.moodle.org/dev/Comment_API ... can you edit it to make sure it's up to date, and in the present tense, and remove 2.0 etc.

            Show
            dougiamas Martin Dougiamas added a comment - Hi, I see "@category comment" in the block etc, this is not part of the API for other plugins. Can you remove these? The @category should just be on the functions/classes that other modules (eg mod/database) call, as well as possibly some of the implementations in those modules (as you have done). I've moved the old spec to http://docs.moodle.org/dev/Comment_API ... can you edit it to make sure it's up to date, and in the present tense, and remove 2.0 etc.
            Hide
            dongsheng Dongsheng Cai added a comment -

            @category removed, working on the doc now.

            Show
            dongsheng Dongsheng Cai added a comment - @category removed, working on the doc now.
            Hide
            samhemelryk Sam Hemelryk added a comment -

            Hi DS,

            Just been looking at this now, my notes are:

            1. @category comment perhaps you havn't pushed up your changes there. Presently that needs review. Certainly the comment libs should be tagged with it right?
            2. comment/lib.php
              • Typo search for costomize
              • line 85 unneeded /*#@-/
              • output method @return should be string|void
              • get_comments @return should be array
              • add missing @param and incorrect @return
              • delete incorrect @return
              • print_comments incorrect @return

            Rest looks fine, thanks DS

            Cheers
            Sam

            Show
            samhemelryk Sam Hemelryk added a comment - Hi DS, Just been looking at this now, my notes are: @category comment perhaps you havn't pushed up your changes there. Presently that needs review. Certainly the comment libs should be tagged with it right? comment/lib.php Typo search for costomize line 85 unneeded /* #@- / output method @return should be string|void get_comments @return should be array add missing @param and incorrect @return delete incorrect @return print_comments incorrect @return Rest looks fine, thanks DS Cheers Sam
            Hide
            dongsheng Dongsheng Cai added a comment -

            Thanks Sam for the review, I updated my branches to fix the problems you mentioned.

            Show
            dongsheng Dongsheng Cai added a comment - Thanks Sam for the review, I updated my branches to fix the problems you mentioned.
            Hide
            stronk7 Eloy Lafuente (stronk7) added a comment -

            Package core_comment is not valid, plz change it to correct package (surely "core" and done). Apart from that... looks perfect, thanks!

            Show
            stronk7 Eloy Lafuente (stronk7) added a comment - Package core_comment is not valid, plz change it to correct package (surely "core" and done). Apart from that... looks perfect, thanks!
            Hide
            dongsheng Dongsheng Cai added a comment -

            Eloy, what's wrong with core_comment? we decided it's "comment" in doc http://docs.moodle.org/dev/Core_APIs#Comment_API_.28comment.29

            Show
            dongsheng Dongsheng Cai added a comment - Eloy, what's wrong with core_comment? we decided it's "comment" in doc http://docs.moodle.org/dev/Core_APIs#Comment_API_.28comment.29
            Hide
            stronk7 Eloy Lafuente (stronk7) added a comment - - edited

            @category comment ==> perfect.
            @package core_comment ==> wrong!

            packages can be only valid components (or frankenstyle plugins or valid subsystems). And core_comment is NONE of those.

            Ask Rajesh, that was confirmed and agreed last week while reviewing other phpdoc-issues.

            Ciao

            Show
            stronk7 Eloy Lafuente (stronk7) added a comment - - edited @category comment ==> perfect. @package core_comment ==> wrong! packages can be only valid components (or frankenstyle plugins or valid subsystems). And core_comment is NONE of those. Ask Rajesh, that was confirmed and agreed last week while reviewing other phpdoc-issues. Ciao
            Hide
            dongsheng Dongsheng Cai added a comment -

            Thanks Eloy

            I changed core_comment to core for package name.

            Show
            dongsheng Dongsheng Cai added a comment - Thanks Eloy I changed core_comment to core for package name.
            Hide
            stronk7 Eloy Lafuente (stronk7) added a comment -

            Integrated, thanks!

            Show
            stronk7 Eloy Lafuente (stronk7) added a comment - Integrated, thanks!
            Hide
            stronk7 Eloy Lafuente (stronk7) added a comment -

            nobody tested this

            Show
            stronk7 Eloy Lafuente (stronk7) added a comment - nobody tested this
            Hide
            stronk7 Eloy Lafuente (stronk7) added a comment -

            It is late here and I'm very tired but I didn't want to go to sleep before expressing my admiration for your amazing collaboration. Thanks!

            Closing as fixed, heading to zzzZZZzzz, niao

            Show
            stronk7 Eloy Lafuente (stronk7) added a comment - It is late here and I'm very tired but I didn't want to go to sleep before expressing my admiration for your amazing collaboration. Thanks! Closing as fixed, heading to zzzZZZzzz, niao

              People

              • Votes:
                0 Vote for this issue
                Watchers:
                0 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved:
                  Fix Release Date:
                  25/Jun/12