Moodle
  1. Moodle
  2. MDL-30971

Check and complete documentation for all Core APIs

    Details

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

      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.

        Issue Links

        Progress
        Resolved Sub-Tasks

        Sub-Tasks

        There are no Sub-Tasks for this issue.

          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

            People

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

              Dates

              • Created:
                Updated: