Permalink
Browse files

Enabled automated doc building. Changes:

-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
  • Loading branch information...
1 parent 9986fc1 commit e0c659b34b8992111bcc64d3f0eea75dfa193412 Alexander Kampmann committed Mar 1, 2012
Showing with 205 additions and 3 deletions.
  1. +8 −0 .gitignore
  2. +38 −0 build.xml
  3. +6 −1 include/acl_selectors.php
  4. +2 −2 library/phpsec/Net/SSH1.php
  5. +6 −0 util/db_update.php
  6. +145 −0 util/docblox_errorchecker.php
View
@@ -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
View
@@ -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>
@@ -1,6 +1,11 @@
<?php
+/**
+ *
+ */
-
+/**
+ * @package acl_selectors
+ */
function group_select($selname,$selclass,$preselected = false,$size = 4) {
$a = get_app();
@@ -730,8 +730,8 @@ function interactiveWrite($cmd)
/**
* Reads the output of an interactive shell.
*
- * Requires PHP 4.3.0 or later due to the use of the stream_select() function. If you see stuff like
- * "[00m", you're seeing ANSI escape codes. According to
+ * Requires PHP 4.3.0 or later due to the use of the stream_select() function. If you see crap,
+ * you're seeing ANSI escape codes. According to
* {@link http://support.microsoft.com/kb/101875 How to Enable ANSI.SYS in a Command Window}, "Windows NT
* does not support ANSI escape sequences in Win32 Console applications", so if you're a Windows user,
* there's not going to be much recourse.
View
@@ -1,5 +1,11 @@
<?php
+/**
+* @package util
+*/
+/*
+* require boot.php
+*/
require_once("boot.php");
$a = new App;
@@ -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. ";

0 comments on commit e0c659b

Please sign in to comment.