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

Choosing PHPdocs generator for Moodle code

    XMLWordPrintable

    Details

    • Type: Task
    • Status: Closed
    • Priority: Minor
    • Resolution: Duplicate
    • Component/s: docs.moodle.org/dev
    • Labels:
      None

      Description

      There are several options available on the market. Among them are
      PHPDocumentor http://www.phpdoc.org/
      PHPXref http://phpxref.sourceforge.net/
      Doxygen http://www.doxygen.org
      and others... http://en.wikipedia.org/wiki/Comparison_of_documentation_generators

      Nobody is perfect, we need to find the one that suits us the most.

      I did some research on Doxygen (the most maintained one among listed above) and this is my resume:
      Doxygen creates a very nice looking pages with class hierarchy diagrams, index pages, etc.
      It also has some bugs/features:
      1. File-level phpdocs are not recognized unless there is a @file token in them. And we don't have this token in moodle. Other generators automatically recognize the first phpdocs block as file-level.
      2. define() statement is displayed as enumeration instead of constant (https://bugzilla.gnome.org/show_bug.cgi?id=358976)
      3. If variable comment only has one line starting with @var - it is ignored (https://bugzilla.gnome.org/show_bug.cgi?id=626105)
      4. html file names are generated in the same directory (or split between random directories), and it is impossible to guess the name of file by the name of class/function

      The workarounds:
      1-3. pre-process files with some script before feeding them to Doxygen - add @file in first phpdoc, change all define() to const and remove @var when needed
      4. we create a script that runs through already generated indexes of files, directories, classes, functions (very easy to parse) and fill the DB table with the mapping.
      We developers can insert tokens in dev docs like
      [phpdocs:class:core_renderer]
      [phpdocs:file:lib/moodlelib.php]
      [phpdocs:code:lib/moodlelib.php]
      [phpdocs:element:CLASSNAME::ELEMENTNAME]
      etc. and there is some script that lookup in our table and converts it into URL
      (note, the table also has a version field)

        Attachments

          Issue Links

            Activity

              People

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

                Dates

                • Created:
                  Updated:
                  Resolved: