Uploaded image for project: 'Moodle Community Sites'
  1. Moodle Community Sites
  2. MDLSITE-355

has_capability_in_accessdata must be documented

    Details

    • Type: Bug
    • Status: Closed
    • Priority: Major
    • Resolution: Fixed
    • Component/s: docs.moodle.org
    • Labels:
      None

      Description

      Function has_capability_in_accessdata in lib/accesslib implements the algorithm that determines a user's permissions in a given context. The algorithm needs to be documented in docs.moodle.org.

      There's even a To do in the code: "Document how it works"

      Some developers believe that it is unnecessary for users to understand the algorithm. See http://moodle.org/mod/forum/discuss.php?d=90140. As someone who is frequently called upon to explain "edge" cases, I reject this position. If I can't get away with hand-waving, then neither can you!

      Providing a set of examples (as suggested by Tim Hunt) is good, but not good enough.

      Here's a suggestion: A developer who understands the code should write a pseudocode version of the algorithm and add it to the developer documentation. If it is written as a RECURSIVE function, it will be short and easy to understand by anyone with a programming background. Such people can use it as the basis for their own textual descriptions and examples.

        Gliffy Diagrams

          Attachments

            Activity

            Hide
            tsala Helen Foster added a comment -

            Added Martín and Petr as watchers for their comments on this issue.

            Show
            tsala Helen Foster added a comment - Added Martín and Petr as watchers for their comments on this issue.
            Hide
            jisner John Isner added a comment -

            I documented the function in the docs wiki article http://docs.moodle.org/en/How_permissions_are_calculated.
            You can close this issue.

            Show
            jisner John Isner added a comment - I documented the function in the docs wiki article http://docs.moodle.org/en/How_permissions_are_calculated . You can close this issue.
            Hide
            skodak Petr Skoda added a comment -

            Thanks for working on this, closing...

            Show
            skodak Petr Skoda added a comment - Thanks for working on this, closing...

              People

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

                Dates

                • Created:
                  Updated:
                  Resolved: