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

Allow inline phpdocs, new @return types and @global tag

    XMLWordPrintable

    Details

    • Type: Bug
    • Status: Closed
    • Priority: Minor
    • Resolution: Fixed
    • Component/s: Coding style
    • Labels:
      None

      Description

      This issue ended discussing about more things/types/tags than the initially planned.

      All these were discussed, voted and decided here:
      1. about to allow type-hinting with inline-phpdocs before an assignment when impossible to determine from @return information.
      2. about to start using correct types everywhere (self/static/$this/arra[]).
      3. about to allow @global.

      For final proposal and its discussion and voting, read here.
      For the effective changes to coding style, read here.

      Right now we are only allowing PHPDocs @ some well defined places. See http://docs.moodle.org/dev/Coding_style#Files and next sections (basically files, classes, interfaces, methods, and properties).

      But that's not enough to facilitate IDEs autocompletion for local variables, mainly because the @return specification does not allow hinting the type of arrays.

      For example, this code:

      $files = $this->get_draft_files('rolepreset');
      

      retuns an array of stored_file objects, but the IDE has no way to know it, so it won't bring you autocompletion for any use of those variables. So, for example:

      $file = reset($files);
      

      $file->.... won't autocomplete at all.

      Given that, there are some developers that have started using this as a technique to bring autocompletion working:

      /** @var stored_file $file */
      $file = reset($files);
      

      $file->.... will autocomplete ok.

      But, right now, that's against the coding style because we don't allow PHPDocs for local variables at all (and the code checker reports it).

      In the other side, looking for more information, I ended here where it points about some IDEs (Netbeans, phpStorm..) being able to provide autocompletion by using this syntax in return types in the called function / method:

      /**
       * ....
       * ....
       * @return stored_file[]
       */
      function get_draft_files() {...}
      

      By using that we are:

      1) Allowing IDEs to autocomplete better. Sure it does not cover everything (nested array/object structures...) but at least the very common case of simple arrays.
      2) Makes not needed to support inline PHPDocs for local variables.
      3) Provides better PHPDoc documentation, being able to specify the class of the array (assuming system X will be able to process that).

      ======

      Offtopic, note that also it's possible to get the IDEs autocompleting sometime by casting so:

      $file = (stored_file)reset($files);
      

      will lead to better autocompletion, but we should not be casting everywhere, just for hinting IMO, so I've left that out as a possible solution.

      =====

      So, this is, basically about to decide:

      A) Should we allow PHPDocs for local variables hinting (yes/no).
      B) Should we move from "@return array" to more specific "return type[]" syntax (yes/no). Note this requires research to verify how IDEs and X-like systems support it.

      Let's discuss about this. Ciao

        Attachments

          Issue Links

            Activity

              People

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

                Dates

                • Created:
                  Updated:
                  Resolved: