util/docblox_errorchecker.php

   1 <?php
   2 /**
   3  * When I installed docblox, I had the experience that it does not generate any output at all.
   4  * This script may be used to find that kind of problems with the documentation build process.
   5  * If docblox generates output, use another approach for debugging.
   6  *
   7  * Basically, docblox takes a list of files to build documentation from. This script assumes there is a file or set of files
   8  * breaking the build when it is included in that list. It tries to calculate the smallest list containing these files.
   9  * Unfortunatly, the original problem is NP-complete, so what the script does is a best guess only.
  10  *
  11  * So it starts with a list of all files in the project.
  12  * If that list can't be build, it cuts it in two parts and tries both parts independently. If only one of them breaks,
  13  * it takes that one and tries the same independently. If both break, it assumes this is the smallest set. This assumption
  14  * is not necessarily true. Maybe the smallest set consists of two files and both of them were in different parts when
  15  * the list was divided, but by now it is my best guess. To make this assumption better, the list is shuffled after every step.
  16  *
  17  * After that, the script tries to remove a file from the list. It tests if the list breaks and if so, it
  18  * assumes that the file it removed belongs to the set of errorneous files.
  19  * This is done for all files, so, in the end removing one file leads to a working doc build.
  20  *
  21  * @package util
  22  * @author Alexander Kampmann
  23  */
  24
  25 /**
  26  * This function generates a comma seperated list of file names.
  27  *
  28  * @package util
  29  *
  30  * @param array $fileset Set of file names
  31  *
  32  * @return string comma-seperated list of the file names
  33  */
  34 function namesList($fileset) {
  35         $fsparam="";
  36         foreach($fileset as $file) {
  37                 $fsparam=$fsparam.",".$file;
  38         }
  39         return $fsparam;
  40 };
  41
  42 /**
  43  * This functions runs phpdoc on the provided list of files
  44  * @package util
  45  *
  46  * @param array $fileset Set of filenames
  47  *
  48  * @return bool true, if that set can be built
  49  */
  50 function runs($fileset) {
  51         $fsParam=namesList($fileset);
  52         exec('docblox -t phpdoc_out -f '.$fsParam);
  53         if(file_exists("phpdoc_out/index.html")) {
  54                 echo "\n Subset ".$fsParam." is okay. \n";
  55                 exec('rm -r phpdoc_out');
  56                 return true;
  57         } else {
  58                 echo "\n Subset ".$fsParam." failed. \n";
  59                 return false;
  60         }
  61 };
  62
  63 /**
  64  * This functions cuts down a fileset by removing files until it finally works.
  65  * it was meant to be recursive, but php's maximum stack size is to small. So it just simulates recursion.
  66  *
  67  * In that version, it does not necessarily generate the smallest set, because it may not alter the elements order enough.
  68  *
  69  * @package util
  70  *
  71  * @param array $fileset set of filenames
  72  * @param int $ps number of files in subsets
  73  *
  74  * @return array a part of $fileset, that crashes
  75  */
  76 function reduce($fileset, $ps) {
  77         //split array...
  78         $parts=array_chunk($fileset, $ps);
  79         //filter working subsets...
  80         $parts=array_filter($parts, "runs");
  81         //melt remaining parts together
  82         if(is_array($parts)) {
  83                 return array_reduce($parts, "array_merge", array());
  84         }
  85         return array();
  86 };
  87
  88 //return from util folder to frindica base dir
  89 $dir='..';
  90
  91 //stack for dirs to search
  92 $dirstack=array();
  93 //list of source files
  94 $filelist=array();
  95
  96 //loop over all files in $dir
  97 while($dh=opendir($dir)) {
  98         while($file=readdir($dh)) {
  99                 if(is_dir($dir."/".$file)) {
 100                         //add to directory stack
 101                         if($file!=".." && $file!=".") {
 102                                 array_push($dirstack, $dir."/".$file);
 103                                 echo "dir ".$dir."/".$file."\n";
 104                         }
 105                 } else  {
 106                         //test if it is a source file and add to filelist
 107                         if(substr($file, strlen($file)-4)==".php") {
 108                                 array_push($filelist, $dir."/".$file);
 109                                 echo $dir."/".$file."\n";
 110                         }
 111                 }
 112         }
 113         //look at the next dir
 114         $dir=array_pop($dirstack);
 115 }
 116
 117 //check the entire set
 118 if(runs($filelist)) {
 119         echo "I can not detect a problem. \n";
 120         exit;
 121 }
 122
 123 //check half of the set and discard if that half is okay
 124 $res=$filelist;
 125 $i=0;
 126 do {
 127         $i=count($res);
 128         echo $i."/".count($fileset)." elements remaining. \n";
 129         $res=reduce($res, count($res)/2);
 130         shuffle($res);
 131 } while(count($res)<$i);
 132
 133 //check one file after another
 134 $needed=array();
 135
 136 while(count($res)!=0) {
 137         $file=array_pop($res);
 138
 139         if(runs(array_merge($res, $needed))) {
 140                 echo "needs: ".$file." and file count ".count($needed);
 141                 array_push($needed, $file);
 142         }
 143 }
 144
 145 echo "\nSmallest Set is: ".namesList($needed)." with ".count($needed)." files. ";