Raydium 3D Game Engine

Official forum for everything about Raydium, ManiaDrive, MeMak, ...
It is currently Tue Oct 08, 2024 8:20 am

All times are UTC




Post new topic Reply to topic  [ 1 post ] 
Author Message
 Post subject: new documentation script
PostPosted: Sat Jun 14, 2008 6:53 pm 
Offline
User avatar

Joined: Thu Sep 29, 2005 2:59 pm
Posts: 828
According the comments the documentation system needs to be improved. Here a first step, even if the real problem is the lack of comments.
I've tunned the old documentation script. It has a lot of errors and bugs, but you can see how should work.

Put this script in raydium/trunk/headers and call it from command line:
Code:
php raydocv2.php &>/dev/null

The dev null is to avoid a lot of output.

This will create a doc subfolder. Into it you'll find an index.html file and another subfolder. That subfolder has (or it should) as many files as functions.
In this way the main file has only a list of chapters and a list of functions. And you will only see the one you choose.

Critics? Fixes (it needs a lot)?

Know bugs:
The chapters has no data
Some function files are not correctly named.
Wiki format has to be HTML'ized
Images are not loaded neither copied

Here the script:
Code:
#!/usr/bin/php
<?
/*
    Raydium - CQFD Corp.
    http://raydium.org/
    License: GPL - GNU General Public License, see "gpl.txt" file.
*/

// This script generates a Wiki(ni) style documentation from comments of
// all header files of Raydium (raydium/header/*.h)
@mkdir("doc");
@mkdir("doc/webdoc");

//creating an index
$salida = @fopen("doc/webdoc/index.html", 'w+');
$guardado=$salida;
$page="";
$chapters=array();
$index=array();
//$page="http://wiki.raydium.org/wiki/RaydiumApiReference";
//intro text
$intro="
<h1>Raydium API Reference</h1>
<p>This document is the most up-to-date version.</p>
<p><cite>This is a work in progress.</cite></p>
<p>There are  some errors and wrong informations. Try it, wait, or contribute ;)</p>

<ul>
   <li>
      <a href=$page#chapters>Chapter index</a>
   </li>
   <li>
      <a href=$page#functions>Function index</a>
   </li>
</ul>

<hr/>
<p>This document is autogenerated, any change will be lost, use URL-TO-RaydiumApiReferenceComments for any need.</p>

<hr/>
";




/*************************************************************/
function getTagLine($tag,$lines,$from=0)
{
    for($i=$from;$i<count($lines);$i++)
    {
        $l=$lines[$i];      
        if(substr(trim($l),0,strlen($tag))==$tag)      
            return $i;
    }
    return -1;
}

/*************************************************************/
function getVersion()
{
    $file="../common.h";
    $f=file($file);
    $maj=getTagLine("#define RAYDIUM_MAJOR",$f);
    $min=getTagLine("#define RAYDIUM_MINOR",$f);

    $maj=str_replace("\t"," ",trim($f[$maj]));
    $min=str_replace("\t"," ",trim($f[$min]));

    $maj=explode(" ",$maj);
    $min=explode(" ",$min);
    $maj=$maj[count($maj)-1];
    $min=$min[count($min)-1];

    return sprintf("%d.%03d",$maj,$min);
}

/*************************************************************/
function getMain($filename,$offset)
{
    $f=file($filename);
    $l=getTagLine("/*=",$f);
    if($l==-1)
        return -1;
    $res=trim($f[$l+$offset]);
    return $res;
}

/*************************************************************/
function getPriority($filename)
{
    $res=trim(getMain($filename,2));
    if(is_numeric($res))
        return $res;
    else
        return -1;
}

/*************************************************************/
function getTitle($filename)
{
    return trim(getMain($filename,1));
}

/*************************************************************/
function getHeaders($directory)
{
    $res=array();
    if (is_dir($directory))
        {
       if ($dh = opendir($directory))
       {
           while (($file = readdir($dh)) !== false)
           {
          if(substr($file,-2)==".h")
          {
              $res[]=$file;
          }
           }
       closedir($dh);
       }
        }
        else echo "'$directory' is not a directory";
    return $res;
}

/*************************************************************/
function h1($str,$addchap=true)
{
   global $chapters;
   static $i=1;
   if($addchap)
      {
      echo "<a name=chap$i></a>";
      fwrite($GLOBALS['salida'],"<a name=chap$i></a>");
      $chapters[$i]=$str;
      $i++;
      }
   echo "\n<h2>$str:</h2>\n";
   //fwrite($GLOBALS['salida'],"<a name=chap$i></a>");
}

/*************************************************************/
function h2($str)
{
    echo "<h3>$str:</h3>\n";
    fwrite($GLOBALS['salida'],"<h3>$str:</h3>\n");
}

/*************************************************************/
function body($str)
{
   echo $str."\n\n";
   fwrite($GLOBALS['salida'],$str."\n\n");
}

/*************************************************************/
function getfunciones($file)
{
   $volcado=file($file);
   $num=0;
   foreach($volcado as $item)
   {
      if(substr($item,0,9)=='function ')
      {
         //print substr($item,9)."<br/>\n";
         $num++;
      }
   }
   return $num;
}

/*************************************************************/
function intro($str)
{
   $str=str_replace("{DATE}","Generado: ".date("d-m-Y H:i:s"),$str);
   $str=str_replace("{VERSION}",getVersion(),$str);
   echo $str;
   fwrite($GLOBALS['salida'],$str);
}

/*************************************************************/
function addToIndex($f)
{
    static $i=0;
    global $index;

    $p=strpos($f,"raydium_");
    if($p!==false)
        $f=substr($f,$p);
    else
        $f="unsupported - $f";

    $index[$i]=$f."|$i";
    return $i++;
}


/**********************************************************/
/************************ Main ****************************/
/**********************************************************/

$id="";
$files=getHeaders(".");
if($files==-1)
    die("No header found");

unset($sorted);
for($i=0;$i<count($files);$i++)
{
    $file=$files[$i];
    $p=getPriority($file);
    if($p==-1)
   $p=999000+$i;
   
    while(isset($sorted[$p]))
   $p++;
    $sorted[$p]=$file;
}
ksort($sorted);
$sorted=array_values($sorted);

// Files are sorted, now

//generating introduction
intro($intro);

for($i=0;$i<count($sorted);$i++)
    {
    $file=$sorted[$i];
    //obtenemos los titulos
    $title=getTitle($file);
    $funciones=getfunciones($file);

    //if no tittles, there is no doc
    if($title==-1)
   {
       //h1(($i+1)." No documentation for $file.");
        h1(" No documentation for $file.");
       continue;
   }
   
    //puttint the title
    h1(($i+1)." $title");
   
    $f=file($file);
    $last=0;
    $n=0;
    while(($l=getTagLine("/**",$f,$last))!=-1)
   {
        echo getcwd() . "\n";
      global $salida;
      $ourFileName = "doc/webdoc/doc-tmp.html";
      $salida = fopen($ourFileName, 'w+') or die("can't create file");
       $title=trim($f[$l-1]);
        //$title=&(strstr($title,'function '));
      
      //print ("ASDFASDFASDF: ".$title."<br>");
       if($title=="")
           $title="// unknown item";
          
       // types:
       // 1 - Comment (//)
       // 2 - Macro (#)
       // 3 - Code (...)
       $type=3;
       if($title[0]=="/")
        {
            $type=1;
            $com_type=$title[1];
            $title=trim(substr($title,2));
            if($com_type=='*')
           {
               $title=str_replace( "*/", "", $title);
               $title=trim($title);
           }
        }

       if($title[0]=="#")
           {
           $type=2;
           $pos=strpos($title,")");
           if($pos)
          {
          $title=substr($title,0,$pos+1);
          }
           $title=trim(str_replace("#define ","",$title))." (macro)";
          
           }

       if($type==3)
           {
           if(substr($title,0,7)=="extern ")
          $title=trim(substr($title,7));
           if(substr($title,0,9)=="__rayapi ")
          $title=trim(substr($title,9));
           if($title[strlen($title)-1]==";")
          $title=substr($title,0,-1);
           $title=trim(str_replace("**","* *",$title));
           }
   
       if($type==2 || $type==3)
           $id=addToIndex($title);
   
        //link with the item
      $title=preg_replace('/^function/','',$title);
      h2("<a name=$id></a>".($i+1).".".($n+1)." ".$title);
       //h2('""'."<a name=$id></a>".'""'.($i+1).".".($n+1)." $title");
   
       $last=$l+1;
       $end=getTagLine("**/",$f,$last);
       if($end==-1)
           die("expected '**/' (started line $l)");
   
       unset($body);
    /*   for($j=$l+1;$j<$end;$j++)
           {
           $lj=trim($f[$j]);
           if($lj=="")
          $lj="\n\n";
           else
          $lj.=" ";
           $body[]=$lj;
           }
       $str=implode("",$body);*/
       for($j=$l+1;$j<$end;$j++)
           {
           $lj=trim($f[$j]);
           $body[]=$lj;
           }
       $str=@implode("\n",$body);
       body($str);
   
       $last=$end+1;
       $n++;
        fwrite($salida,$title);   
      fwrite($salida,'<p></p><p><a href="index.html">Back to menu</a></p>');   
      fclose($salida);
      rename("doc/webdoc/doc-tmp.html", "doc/webdoc/doc-$id.html");
       }
    }

$salida=$guardado;
//h1('<a name=chapters></a>Chapters',false);
fwrite($GLOBALS['salida'],('<a name="chapters"></a><h1>Chapter list</h1>')."\n");
fwrite($GLOBALS['salida'],'<ul>'."\n");
//sort chapters alphabetically
sort($chapters);
foreach($chapters as $key => $val)
{
    //echo('<h3>'."<a href=$page#chap$key>$val</a>".'</h3>')."\n";
   fwrite($GLOBALS['salida'],("<li><a href=$page#chap$key>$val</a></li>")."\n");   
}
fwrite($GLOBALS['salida'],'</ul>'."\n");

sort($index);
//h1('<a name=index></a>Function Index');
fwrite($GLOBALS['salida'],('<a name="functions"></a><h1>Function list</h1>')."\n");
fwrite($GLOBALS['salida'],'<ul>'."\n");
for($i=0;$i<count($index);$i++)
{
    $j=explode("|",$index[$i]);
    $k=$j[0];
    $l=$j[1];
    //echo "<a href=$page#$l><tt>$k</tt></a><br/>\n";
   fwrite($GLOBALS['salida'],"<li><a href=doc-$l.html><tt>$k</tt></a></li>\n");
}
fwrite($GLOBALS['salida'],'</ul>'."\n");
fwrite($GLOBALS['salida'],"<hr/><p></p>\n");
fclose($salida);



Top
 Profile  
 
Display posts from previous:  Sort by  
Post new topic Reply to topic  [ 1 post ] 

All times are UTC


Who is online

Users browsing this forum: No registered users and 5 guests


You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot post attachments in this forum

Search for:
Jump to:  
cron
Powered by phpBB® Forum Software © phpBB Group