Moodle
  1. Moodle
  2. MDL-30984

comment API, check and update DocBlock

    Details

    • Type: Task Task
    • Status: Closed
    • Priority: Minor 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

          Activity

          Hide
          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
          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 Cai added a comment -

          @category removed, working on the doc now.

          Show
          Dongsheng Cai added a comment - @category removed, working on the doc now.
          Hide
          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
          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 Cai added a comment -

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

          Show
          Dongsheng Cai added a comment - Thanks Sam for the review, I updated my branches to fix the problems you mentioned.
          Hide
          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
          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 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 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
          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
          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 Cai added a comment -

          Thanks Eloy

          I changed core_comment to core for package name.

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

          Integrated, thanks!

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

          nobody tested this

          Show
          Eloy Lafuente (stronk7) added a comment - nobody tested this
          Hide
          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
          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: