]> git.mxchange.org Git - friendica.git/commitdiff
Enabled automated doc building. Changes:
authorAlexander Kampmann <programmer@nurfuerspam.de>
Thu, 1 Mar 2012 10:44:33 +0000 (11:44 +0100)
committerAlexander Kampmann <programmer@nurfuerspam.de>
Thu, 1 Mar 2012 10:44:33 +0000 (11:44 +0100)
-build.xml, phing build file
-@package tags at acl_selector.php and db_update.php
-added documentation and some IDE files to .gitignore
-automated tool to find files that corrupt the doc build process
-removed ansi characters from SSH1.php, docBlox could not handle them

.gitignore
build.xml [new file with mode: 0644]
include/acl_selectors.php
library/phpsec/Net/SSH1.php
util/db_update.php
util/docblox_errorchecker.php [new file with mode: 0644]

index 3dfb8a903a4e7a9587c7d3c25538ff43a7aee996..6302bc1c8bcdd16345778ff3186ca5fec060b4a6 100755 (executable)
@@ -10,3 +10,11 @@ home.html
 addon
 *~
 
+#ignore documentation, it should be newly built 
+doc/api
+
+#ignore config files from eclipse, we don't want IDE files in our repository
+.project
+.buildpath
+.externalToolBuilders
+.settings
diff --git a/build.xml b/build.xml
new file mode 100644 (file)
index 0000000..83c5300
--- /dev/null
+++ b/build.xml
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<project name="friendica" default="test">
+
+       <!-- =================================== -->
+       <!-- Target: test -->
+       <!-- this target runs all test files -->
+       <!-- =================================== -->
+
+       <target name="test">
+               <!-- there are no tests by now, so, nothing to do -->
+       </target>
+
+       <!-- ===================================================== -->
+       <!-- Target: clean-doc -->
+       <!-- this target removes documentation from a previous run -->
+       <!-- ===================================================== -->
+       <target name="doc-clean">
+               <echo msg="Removing old documentation..." />
+               <delete dir="./doc/api/" />
+               <echo msg="Generate documentation directory..." />
+               <mkdir dir="./doc/api/" />
+       </target>
+
+       <!-- ====================================== -->
+       <!-- Target: doc -->
+       <!-- this target builds all documentation -->
+       <!-- ====================================== -->
+       <target name="doc" depends="doc-clean">
+               <echo msg="Building documentation..." />
+               <docblox title="Friendica API" destdir="./doc/api">
+                       <fileset dir=".">
+                               <include name="**/*.php" />
+                       </fileset>
+               </docblox>
+       </target>
+
+</project>
index 6070b7db21124d046d2a197d7532fd6ea55a08f5..67d8cebdebde0989efb5922730625c69605a39d6 100755 (executable)
@@ -1,6 +1,11 @@
 <?php
+/**
+ * 
+ */
 
-
+/**
+ * @package acl_selectors 
+ */
 function group_select($selname,$selclass,$preselected = false,$size = 4) {
 
        $a = get_app();
index 6986a8450d67c989a67f2b62540623fdd4b3d575..7220ee402350128756906d32168bb59844cc5b9e 100755 (executable)
@@ -730,8 +730,8 @@ class Net_SSH1 {
     /**\r
      * Reads the output of an interactive shell.\r
      *\r
-     * Requires PHP 4.3.0 or later due to the use of the stream_select() function.  If you see stuff like\r
-     * "\e[00m", you're seeing ANSI escape codes.  According to\r
+     * Requires PHP 4.3.0 or later due to the use of the stream_select() function.  If you see crap, \r
+     * you're seeing ANSI escape codes.  According to\r
      * {@link http://support.microsoft.com/kb/101875 How to Enable ANSI.SYS in a Command Window}, "Windows NT\r
      * does not support ANSI escape sequences in Win32 Console applications", so if you're a Windows user,\r
      * there's not going to be much recourse.\r
index 1da2a99091b442ebd4a4a857d421a88e49930484..a6177324aced4fc9cd19a3f2237d6b23f18c4d14 100755 (executable)
@@ -1,5 +1,11 @@
 <?php
+/**
+* @package util
+*/
 
+/* 
+* require boot.php
+*/
 require_once("boot.php");
 
 $a = new App;
diff --git a/util/docblox_errorchecker.php b/util/docblox_errorchecker.php
new file mode 100644 (file)
index 0000000..af4c764
--- /dev/null
@@ -0,0 +1,145 @@
+<?php 
+/**
+ * When I installed docblox, I had the experience that it does not generate any output at all.
+ * This script may be used to find that kind of problems with the documentation build process.
+ * If docblox generates output, use another approach for debugging.
+ *
+ * Basically, docblox takes a list of files to build documentation from. This script assumes there is a file or set of files
+ * breaking the build when it is included in that list. It tries to calculate the smallest list containing these files.
+ * Unfortunatly, the original problem is NP-complete, so what the script does is a best guess only.
+ *
+ * So it starts with a list of all files in the project.
+ * If that list can't be build, it cuts it in two parts and tries both parts independently. If only one of them breaks,
+ * it takes that one and tries the same independently. If both break, it assumes this is the smallest set. This assumption
+ * is not necessarily true. Maybe the smallest set consists of two files and both of them were in different parts when
+ * the list was divided, but by now it is my best guess. To make this assumption better, the list is shuffled after every step. 
+ *
+ * After that, the script tries to remove a file from the list. It tests if the list breaks and if so, it
+ * assumes that the file it removed belongs to the set of errorneous files. 
+ * This is done for all files, so, in the end removing one file leads to a working doc build. 
+ *
+ * @package util
+ * @author Alexander Kampmann
+ */
+
+/**
+ * This function generates a comma seperated list of file names.
+ * 
+ * @package util
+ * 
+ * @param array $fileset Set of file names
+ * 
+ * @return string comma-seperated list of the file names
+ */
+function namesList($fileset) {
+       $fsparam="";
+       foreach($fileset as $file) {
+               $fsparam=$fsparam.",".$file;
+       }
+       return $fsparam;
+};
+
+/**
+ * This functions runs phpdoc on the provided list of files
+ * @package util
+ * 
+ * @param array $fileset Set of filenames
+ * 
+ * @return bool true, if that set can be built
+ */
+function runs($fileset) {
+       $fsParam=namesList($fileset);
+       exec('docblox -t phpdoc_out -f '.$fsParam);
+       if(file_exists("phpdoc_out/index.html")) {
+               echo "\n Subset ".$fsParam." is okay. \n";
+               exec('rm -r phpdoc_out');
+               return true;
+       } else {
+               echo "\n Subset ".$fsParam." failed. \n";
+               return false;
+       }
+};
+
+/**
+ * This functions cuts down a fileset by removing files until it finally works.
+ * it was meant to be recursive, but php's maximum stack size is to small. So it just simulates recursion.
+ *
+ * In that version, it does not necessarily generate the smallest set, because it may not alter the elements order enough.
+ * 
+ * @package util
+ * 
+ * @param array $fileset set of filenames
+ * @param int $ps number of files in subsets
+ * 
+ * @return array a part of $fileset, that crashes
+ */
+function reduce($fileset, $ps) {
+       //split array...
+       $parts=array_chunk($fileset, $ps);
+       //filter working subsets...
+       $parts=array_filter($parts, "runs");
+       //melt remaining parts together
+       if(is_array($parts)) {
+               return array_reduce($parts, "array_merge", array());
+       }
+       return array();
+};
+
+//return from util folder to frindica base dir
+$dir='..';
+
+//stack for dirs to search
+$dirstack=array();
+//list of source files
+$filelist=array();
+
+//loop over all files in $dir
+while($dh=opendir($dir)) {
+       while($file=readdir($dh)) {
+               if(is_dir($dir."/".$file)) {
+                       //add to directory stack
+                       if($file!=".." && $file!=".") {
+                               array_push($dirstack, $dir."/".$file);
+                               echo "dir ".$dir."/".$file."\n";
+                       }
+               } else  {
+                       //test if it is a source file and add to filelist
+                       if(substr($file, strlen($file)-4)==".php") {
+                               array_push($filelist, $dir."/".$file);
+                               echo $dir."/".$file."\n";
+                       }
+               }
+       }
+       //look at the next dir
+       $dir=array_pop($dirstack);
+}
+
+//check the entire set
+if(runs($filelist)) {
+       echo "I can not detect a problem. \n";
+       exit;
+}
+
+//check half of the set and discard if that half is okay
+$res=$filelist;
+$i=0;
+do {
+       $i=count($res);
+       echo $i."/".count($fileset)." elements remaining. \n";
+       $res=reduce($res, count($res)/2);
+       shuffle($res);
+} while(count($res)<$i);
+
+//check one file after another
+$needed=array();
+
+while(count($res)!=0) {
+       $file=array_pop($res);
+
+       if(runs(array_merge($res, $needed))) {
+               echo "needs: ".$file." and file count ".count($needed);
+               array_push($needed, $file);
+       }
+}
+
+echo "\nSmallest Set is: ".namesList($needed)." with ".count($needed)." files. ";