Moodle
  1. Moodle
  2. MDL-30971

Check and complete documentation for all Core APIs

    Details

    • Type: Improvement Improvement
    • Status: Closed
    • Priority: Major Major
    • Resolution: Inactive
    • Affects Version/s: 2.2, 2.2.1
    • Fix Version/s: STABLE backlog
    • Component/s: Documentation
    • Labels:
    • Affected Branches:
      MOODLE_22_STABLE

      Description

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

      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

          Issue Links

            Activity

            Hide
            Rajesh Taneja added a comment -

            Hello Everyone,

            Below is the summary of what we discussed in SCRUM for moodle document project.

            Overview:
            Purpose of the project is to check/update/add php docblock for core moodle API's, which should comply with Moodle coding style guide.

            Process:
            1. Changes will be submitted via github though tracker for 2.2 and master branch
            2. Peer review will be done by Martin, Michael or Helen.
            3. Integrators should ascertain code coverage and compliance with Moodle coding style guide, for the api
            4. No testing required

            Things to consider:
            1. Moodle coding style guide were updated yesterday, please do take time to read it again.
            2. Tags which are not mentioned in Moodle coding style (like @thow, @examples etc.) are acceptable, but make sure they are standard tags
            3. Some developers used hyphen in @param tag. This is not acceptable.
            4. @link should be used for referencing moodle docs site only.
            5. You can create new or clone the bug to provide updates in small patches, to make integration process smother.

            Note: Next step in project (which will start after completing phpdoc) is to write moodle doc for cope API. It might be handy if you
            keep notes (Overview, glossary, examples, categories, FAQ's etc) for the api you are documenting. Template for this will be available in coming days.

            Show
            Rajesh Taneja added a comment - Hello Everyone, Below is the summary of what we discussed in SCRUM for moodle document project. Overview: Purpose of the project is to check/update/add php docblock for core moodle API's, which should comply with Moodle coding style guide. Process: 1. Changes will be submitted via github though tracker for 2.2 and master branch 2. Peer review will be done by Martin, Michael or Helen. 3. Integrators should ascertain code coverage and compliance with Moodle coding style guide, for the api 4. No testing required Things to consider: 1. Moodle coding style guide were updated yesterday, please do take time to read it again. 2. Tags which are not mentioned in Moodle coding style (like @thow, @examples etc.) are acceptable, but make sure they are standard tags 3. Some developers used hyphen in @param tag. This is not acceptable. 4. @link should be used for referencing moodle docs site only. 5. You can create new or clone the bug to provide updates in small patches, to make integration process smother. Note: Next step in project (which will start after completing phpdoc) is to write moodle doc for cope API. It might be handy if you keep notes (Overview, glossary, examples, categories, FAQ's etc) for the api you are documenting. Template for this will be available in coming days.
            Hide
            Rajesh Taneja added a comment -

            Hello Everyone

            Coding style guide just got updated, Please have a look at:
            http://docs.moodle.org/dev/index.php?title=Coding_style&action=historysubmit&diff=31114&oldid=31098

            Also, core api page is updated to:
            http://docs.moodle.org/dev/index.php?title=Core_APIs&action=historysubmit&diff=31111&oldid=31108

            Summary:
            1. If you feel api is not well named then please feel free to raise an issue or modify it and communicate this to everyone.
            2. @var will use one-liners
            3. @subpackage is replaced with @category. It should highlighting the important classes and functions that people will actually be using in their plugins.

            FYI:
            Purpose of documentation is to let plugin writer find and understand api's. So, label @category depending on what is useful for plugin writers. (Martin Dougiamas: In the case of backup scripts in forum/workshop etc, then I would label those @category backup, simply because they provide excellent examples for people.)

            Show
            Rajesh Taneja added a comment - Hello Everyone Coding style guide just got updated, Please have a look at: http://docs.moodle.org/dev/index.php?title=Coding_style&action=historysubmit&diff=31114&oldid=31098 Also, core api page is updated to: http://docs.moodle.org/dev/index.php?title=Core_APIs&action=historysubmit&diff=31111&oldid=31108 Summary: 1. If you feel api is not well named then please feel free to raise an issue or modify it and communicate this to everyone. 2. @var will use one-liners 3. @subpackage is replaced with @category. It should highlighting the important classes and functions that people will actually be using in their plugins. FYI: Purpose of documentation is to let plugin writer find and understand api's. So, label @category depending on what is useful for plugin writers. (Martin Dougiamas: In the case of backup scripts in forum/workshop etc, then I would label those @category backup, simply because they provide excellent examples for people.)
            Hide
            Martin Dougiamas added a comment -

            Just to be ABSOLUTELY clear on @package and @category

            1) We use @package to mention the full component name everywhere we can (we are currently focussing on API-related files but we'll have to eventually extend this everywhere in Moodle code).

            2) We use @category to highlight classes, files and functions that are important documentation for our APIs. Remember these are just the actual public API bits, useful to plugin authors. Don't label private methods etc.

            Show
            Martin Dougiamas added a comment - Just to be ABSOLUTELY clear on @package and @category 1) We use @package to mention the full component name everywhere we can (we are currently focussing on API-related files but we'll have to eventually extend this everywhere in Moodle code). 2) We use @category to highlight classes, files and functions that are important documentation for our APIs. Remember these are just the actual public API bits, useful to plugin authors. Don't label private methods etc.
            Hide
            Tim Hunt added a comment -

            Has anyone written a script the automatically converts the previous 'right' way to do this to the current way? I.e.

            @package

            {plugintype}
            @subpackage {pluginname}

            to

            @package {plugintype}

            _

            {pluginname}
            Show
            Tim Hunt added a comment - Has anyone written a script the automatically converts the previous 'right' way to do this to the current way? I.e. @package {plugintype} @subpackage {pluginname} to @package {plugintype} _ {pluginname}
            Hide
            Martin Dougiamas added a comment -

            Not that I know of, Tim, sorry. Not sure how much code it would even be useful on.

            Note: just added some core subsystem component examples to the Frankenstyle doc: http://docs.moodle.org/dev/Frankenstyle#Core_subsystems

            Show
            Martin Dougiamas added a comment - Not that I know of, Tim, sorry. Not sure how much code it would even be useful on. Note: just added some core subsystem component examples to the Frankenstyle doc: http://docs.moodle.org/dev/Frankenstyle#Core_subsystems
            Hide
            Aparup Banerjee added a comment -

            i really wish sub-tasks could create sub-tasks

            Show
            Aparup Banerjee added a comment - i really wish sub-tasks could create sub-tasks
            Hide
            Rajesh Taneja added a comment -

            While writing core api doc page, please refer Event API as template for documenting your core api. You can add/remove sections, depending on the core api you are documenting.

            Show
            Rajesh Taneja added a comment - While writing core api doc page, please refer Event API as template for documenting your core api. You can add/remove sections, depending on the core api you are documenting.
            Hide
            Aparup Banerjee added a comment -

            I am slightly confused here. This issue is titled 'Check and update DocBlock in moodle code' , are we going to co-ordinate updating doc pages here too? If so then perhaps the title might need updating.

            Show
            Aparup Banerjee added a comment - I am slightly confused here. This issue is titled 'Check and update DocBlock in moodle code ' , are we going to co-ordinate updating doc pages here too? If so then perhaps the title might need updating.
            Hide
            Rajesh Taneja added a comment -

            Hello Aparup,
            As part of this bug, we are just updating docblock. Some suggested, that it might be easier to write doc pages, hence it's just a pointer for developers to keep in mind (for keeping notes)

            Show
            Rajesh Taneja added a comment - Hello Aparup, As part of this bug, we are just updating docblock. Some suggested, that it might be easier to write doc pages, hence it's just a pointer for developers to keep in mind (for keeping notes)
            Hide
            Marina Glancy added a comment -

            Here is a script that goes through all files and replaces
            @package XXX
            @subpackage YYY

            with

            @package XXX_YYY

            https://gist.github.com/1581626

            Show
            Marina Glancy added a comment - Here is a script that goes through all files and replaces @package XXX @subpackage YYY with @package XXX_YYY https://gist.github.com/1581626
            Hide
            Marina Glancy added a comment - - edited

            Since I missed last week, I'd like to contribute a little to @package/@category discussion now:

            @category is not supported by phpDocumentor for HTML documentation
            http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.category.pkg.html
            And since phpDocumentor is not maintained it is not likely to be supported in future versions

            Neither it is supported in other documentation tools.

            In Doxygen one function/class may be part of several groups (analog of package in phpDocumentor). But in this case the name of category should be the same as the name of package.

            I.e.

            • @package mod_mymodule
            • @category core_backup

            And not "@category backup" as it is currently in http://docs.moodle.org/dev/Coding_style#Files

            Show
            Marina Glancy added a comment - - edited Since I missed last week, I'd like to contribute a little to @package/@category discussion now: @category is not supported by phpDocumentor for HTML documentation http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.category.pkg.html And since phpDocumentor is not maintained it is not likely to be supported in future versions Neither it is supported in other documentation tools. In Doxygen one function/class may be part of several groups (analog of package in phpDocumentor). But in this case the name of category should be the same as the name of package. I.e. @package mod_mymodule @category core_backup And not "@category backup" as it is currently in http://docs.moodle.org/dev/Coding_style#Files
            Hide
            Rajesh Taneja added a comment -

            Updated Coding style guide, defining Package and category tag.

            Show
            Rajesh Taneja added a comment - Updated Coding style guide , defining Package and category tag.
            Hide
            Aparup Banerjee added a comment -

            i was wonder if there was a better way to represent functions/methods that die or exit than simply stating it in the description paragraph. I've come across @uses which may suit this need and add further clarity to developers.

            eg:
            @uses exit or @uses die

            Show
            Aparup Banerjee added a comment - i was wonder if there was a better way to represent functions/methods that die or exit than simply stating it in the description paragraph. I've come across @uses which may suit this need and add further clarity to developers. eg: @uses exit or @uses die
            Hide
            Rajesh Taneja added a comment -

            Updated coding style guide to reflect use of return and @uses die

            Show
            Rajesh Taneja added a comment - Updated coding style guide to reflect use of return and @uses die
            Hide
            Rajesh Taneja added a comment -

            Sam pointed out few things, while reviewing patch for Time API.
            Please have a look at http://tracker.moodle.org/browse/MDL-30993?focusedCommentId=139105&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-139105 and provide feedback

            Show
            Rajesh Taneja added a comment - Sam pointed out few things, while reviewing patch for Time API. Please have a look at http://tracker.moodle.org/browse/MDL-30993?focusedCommentId=139105&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-139105 and provide feedback
            Hide
            Marina Glancy added a comment -

            I agree with Sam on @package
            and also suggest to mention in http://docs.moodle.org/dev/Coding_style#Functions that in special cases for core APIs like time and preference which are groupped in one file, the function MAY have @package or @category tag to overwrite file-level tag for this function.

            I know that lib/moodlelib.php is probably the only file that needs it but still it is already asked several times by core developers and worth mentioning in wiki.

            Also we should give examples in Coding_style about how to write multi-line tags (i.e. @param) and how to use indentation.

            No particular opinion on @access, it seems useless but harmless

            Show
            Marina Glancy added a comment - I agree with Sam on @package and also suggest to mention in http://docs.moodle.org/dev/Coding_style#Functions that in special cases for core APIs like time and preference which are groupped in one file, the function MAY have @package or @category tag to overwrite file-level tag for this function. I know that lib/moodlelib.php is probably the only file that needs it but still it is already asked several times by core developers and worth mentioning in wiki. Also we should give examples in Coding_style about how to write multi-line tags (i.e. @param) and how to use indentation. No particular opinion on @access, it seems useless but harmless
            Hide
            Marina Glancy added a comment -

            We have detected that this issue has been inactive for over two years and also did not collect many votes. It is possible that it has been already implemented in a more recent version of Moodle, or it is not highly demanded. There are unlimited number of ways Moodle functinality can be expanded and improved but we would like to concentrate on the features that will benefit majority of users, and which can not be implemented as plugins. If you have a suggestion for improving Moodle core, and there is no open issue for it in the tracker, please start a new forum discussion to see how many other users agree with you, and then create a new issue providing as many details as possible.

            ==BLK2YIMP20141121==

            Show
            Marina Glancy added a comment - We have detected that this issue has been inactive for over two years and also did not collect many votes. It is possible that it has been already implemented in a more recent version of Moodle, or it is not highly demanded. There are unlimited number of ways Moodle functinality can be expanded and improved but we would like to concentrate on the features that will benefit majority of users, and which can not be implemented as plugins. If you have a suggestion for improving Moodle core, and there is no open issue for it in the tracker, please start a new forum discussion to see how many other users agree with you, and then create a new issue providing as many details as possible. ==BLK2YIMP20141121==

              People

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

                Dates

                • Created:
                  Updated:
                  Resolved: