maintenance/mwdoc-filter.php

   1 <?php
   2 /**
   3  * Doxygen filter to show correct member variable types in documentation.
   4  *
   5  * Should be set in Doxygen INPUT_FILTER as "php mwdoc-filter.php"
   6  *
   7  * Based on
   8  * <https://virtualtee.blogspot.co.uk/2012/03/tip-for-using-doxygen-for-php-code.html>
   9  *
  10  * Improved to resolve various bugs and better MediaWiki PHPDoc conventions:
  11  *
  12  * - Insert variable name after typehint instead of at end of line so that
  13  *   documentation text may follow after "@var Type".
  14  * - Insert typehint into source code before $variable instead of inside the comment
  15  *   so that Doxygen interprets it.
  16  * - Strip the text after @var from the output to avoid Doxygen warnings aboug bogus
  17  *   symbols being documented but not declared or defined.
  18  *
  19  * Copyright (C) 2012 Tamas Imrei <tamas.imrei@gmail.com> https://virtualtee.blogspot.com/
  20  * Copyright (C) 2015 Timo Tijhof
  21  *
  22  * Permission is hereby granted, free of charge, to any person obtaining
  23  * a copy of this software and associated documentation files (the "Software"),
  24  * to deal in the Software without restriction, including without limitation
  25  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
  26  * and/or sell copies of the Software, and to permit persons to whom the
  27  * Software is furnished to do so, subject to the following conditions:
  28  *
  29  * The above copyright notice and this permission notice shall be included
  30  * in all copies or substantial portions of the Software.
  31  *
  32  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  33  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  34  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
  35  * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  36  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  37  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  38  * DEALINGS IN THE SOFTWARE.
  39  */
  40
  41 require_once __DIR__ . '/Maintenance.php';
  42
  43 /**
  44  * Maintenance script that builds doxygen documentation.
  45  * @ingroup Maintenance
  46  */
  47 class MWDocGenFilter extends Maintenance {
  48         public function __construct() {
  49                 parent::__construct();
  50                 $this->addDescription( 'Doxygen filter to fix member variable types in documentation. '
  51                         . 'Used by mwdocgen.php'
  52                 );
  53                 $this->addArg( 'filename', 'PHP file to filter', true );
  54         }
  55
  56         public function execute() {
  57                 $source = file_get_contents( $this->getArg( 0 ) );
  58                 $tokens = token_get_all( $source );
  59
  60                 $buffer = $bufferType = null;
  61                 foreach ( $tokens as $token ) {
  62                         if ( is_string( $token ) ) {
  63                                 if ( $buffer !== null && $token === ';' ) {
  64                                         // If we still have a buffer and the statement has ended,
  65                                         // flush it and move on.
  66                                         echo $buffer;
  67                                         $buffer = $bufferType = null;
  68                                 }
  69                                 echo $token;
  70                                 continue;
  71                         }
  72                         list( $id, $content ) = $token;
  73                         switch ( $id ) {
  74                                 case T_DOC_COMMENT:
  75                                         // Escape slashes so that references to namespaces are not
  76                                         // wrongly interpreted as a Doxygen "\command".
  77                                         $content = addcslashes( $content, '\\' );
  78                                         // Look for instances of "@var Type" not followed by $name.
  79                                         if ( preg_match( '#@var\s+([^\s]+)\s+([^\$]+)#s', $content ) ) {
  80                                                 $buffer = preg_replace_callback(
  81                                                         // Strip the "@var Type" part and remember the type
  82                                                         '#(@var\s+)([^\s]+)#s',
  83                                                         function ( $matches ) use ( &$bufferType ) {
  84                                                                 $bufferType = $matches[2];
  85                                                                 return '';
  86                                                         },
  87                                                         $content
  88                                                 );
  89                                         } else {
  90                                                 echo $content;
  91                                         }
  92                                         break;
  93
  94                                 case T_VARIABLE:
  95                                         if ( $buffer !== null ) {
  96                                                 echo $buffer;
  97                                                 echo "$bufferType $content";
  98                                                 $buffer = $bufferType = null;
  99                                         } else {
 100                                                 echo $content;
 101                                         }
 102                                         break;
 103
 104                                 default:
 105                                         if ( $buffer !== null ) {
 106                                                 $buffer .= $content;
 107                                         } else {
 108                                                 echo $content;
 109                                         }
 110                                         break;
 111                         }
 112                 }
 113         }
 114 }
 115
 116 $maintClass = 'MWDocGenFilter';
 117 require_once RUN_MAINTENANCE_IF_MAIN;