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