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: Commenting, Documentation
    • Labels:
    • Rank:
      37388

      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.

        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: