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 // Warning: Converting this to a Maintenance script may reduce performance.
  42 if ( PHP_SAPI != 'cli' ) {
  43         die( "This filter can only be run from the command line.\n" );
  44 }
  45
  46 $source = file_get_contents( $argv[1] );
  47 $tokens = token_get_all( $source );
  48
  49 $buffer = $bufferType = null;
  50 foreach ( $tokens as $token ) {
  51         if ( is_string( $token ) ) {
  52                 if ( $buffer !== null && $token === ';' ) {
  53                         // If we still have a buffer and the statement has ended,
  54                         // flush it and move on.
  55                         echo $buffer;
  56                         $buffer = $bufferType = null;
  57                 }
  58                 echo $token;
  59                 continue;
  60         }
  61         list( $id, $content ) = $token;
  62         switch ( $id ) {
  63                 case T_DOC_COMMENT:
  64                         // Escape slashes so that references to namespaces are not
  65                         // wrongly interpreted as a Doxygen "\command".
  66                         $content = addcslashes( $content, '\\' );
  67                         // Look for instances of "@var Type" not followed by $name.
  68                         if ( preg_match( '#@var\s+([^\s]+)\s+([^\$]+)#s', $content ) ) {
  69                                 $buffer = preg_replace_callback(
  70                                         // Strip the "@var Type" part and remember the type
  71                                         '#(@var\s+)([^\s]+)#s',
  72                                         function ( $matches ) use ( &$bufferType ) {
  73                                                 $bufferType = $matches[2];
  74                                                 return '';
  75                                         },
  76                                         $content
  77                                 );
  78                         } else {
  79                                 echo $content;
  80                         }
  81                         break;
  82
  83                 case T_VARIABLE:
  84                         if ( $buffer !== null ) {
  85                                 echo $buffer;
  86                                 echo "$bufferType $content";
  87                                 $buffer = $bufferType = null;
  88                         } else {
  89                                 echo $content;
  90                         }
  91                         break;
  92
  93                 default:
  94                         if ( $buffer !== null ) {
  95                                 $buffer .= $content;
  96                         } else {
  97                                 echo $content;
  98                         }
  99                         break;
 100         }
 101 }